nativemason 0.0.0-stage → 0.3.0

package/dist/core/accessibility.js

@@ -0,0 +1,55 @@
+/** WCAG relative luminance for previously validated opaque sRGB channels. */
+export function solidContrastRatio(foreground, background) {
+    const luminance = (rgb) => rgb.map(value => { const x = value / 255; return x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4; }).reduce((sum, value, index) => sum + value * [0.2126, 0.7152, 0.0722][index], 0);
+    const first = luminance(foreground), second = luminance(background);
+    return (Math.max(first, second) + 0.05) / (Math.min(first, second) + 0.05);
+}
+/** Bounded evidence checks; never infers native assistive-technology behavior. */
+export function inspectAccessibility(snapshot) {
+    const findings = [];
+    const add = (code, status, ids, message) => findings.push({ code, status, elementIds: ids, message, platform: snapshot.platform });
+    if (snapshot.status !== 'stable')
+        return [{ code: 'RTL_EVIDENCE', status: 'unavailable', elementIds: [], message: 'Accessibility checks require a settled capture', platform: snapshot.platform }];
+    const byId = new Map(snapshot.nodes.map(node => [node.id, node]));
+    const inactive = (node) => { for (let parent = node.parentId; parent; parent = byId.get(parent)?.parentId ?? null)
+        if (byId.get(parent)?.accessibility?.disabled)
+            return true; return node.accessibility?.disabled === true; };
+    for (const node of snapshot.nodes) {
+        const evidence = node.accessibility;
+        if (snapshot.platform !== 'web' && evidence?.directionSource === 'native-global')
+            add('RTL_EVIDENCE', 'unavailable', [node.id], 'I18nManager provides only a global direction; this node’s resolved Yoga direction was not measured');
+        if (evidence?.hidden || evidence?.accessible === false) {
+            if (snapshot.platform === 'web' && typeof evidence.browser?.focusOrder === 'number')
+                add('FOCUS_ORDER', 'advisory', [node.id], 'Estimated DOM sequential focus position: ' + evidence.browser.focusOrder + '. This control is hidden from the accessibility tree, and the estimate is not verified assistive-technology order.');
+            continue;
+        }
+        const interactive = node.kind === 'Pressable' || node.kind === 'TextInput' || ['button', 'link', 'checkbox', 'switch', 'radio'].includes(node.role ?? '') || evidence?.focusable === true;
+        if (interactive) {
+            if (snapshot.platform === 'web' && evidence?.browser?.name !== null && evidence?.browser?.name !== undefined)
+                add('ACCESSIBLE_NAME', evidence.browser.name.trim() ? 'pass' : 'fail', [node.id], evidence.browser.name.trim() ? 'Chromium computed a nonempty accessible name' : 'Chromium computed an empty accessible name');
+            else if (evidence?.authoredLabel !== undefined)
+                add('ACCESSIBLE_NAME', evidence.authoredLabel.trim() ? 'advisory' : 'fail', [node.id], evidence.authoredLabel.trim() ? 'An explicit label is authored; native spoken output has not been measured' : 'The explicit accessible label is empty');
+            else
+                add('ACCESSIBLE_NAME', 'unavailable', [node.id], 'A derived accessible name was not measured; a missing explicit label alone does not prove an unlabeled control');
+            const order = evidence?.browser?.focusOrder;
+            add('FOCUS_ORDER', order === null || order === undefined ? 'unavailable' : 'advisory', [node.id], typeof order === 'number' ? 'Estimated DOM sequential focus position: ' + order + '. This is not verified assistive-technology order.' : 'Sequential focus order is unavailable for this control');
+        }
+        if (node.kind === 'Text' || node.kind === 'TextInput') {
+            const contrast = evidence?.browser?.contrast;
+            if (inactive(node))
+                add('TEXT_CONTRAST', 'unavailable', [node.id], 'Text belongs to an inactive control and is exempt from ordinary WCAG text contrast evaluation');
+            else if (contrast?.status === 'measured' && contrast.ratio !== undefined && contrast.requiredRatio !== undefined)
+                add('TEXT_CONTRAST', contrast.ratio >= contrast.requiredRatio ? 'pass' : 'fail', [node.id], 'Computed opaque-style contrast ' + contrast.ratio.toFixed(2) + '; required ' + contrast.requiredRatio);
+            else
+                add('TEXT_CONTRAST', 'unavailable', [node.id], contrast?.reason ?? 'Native foreground/background pixel contrast has not been measured');
+        }
+        if (evidence?.direction === 'rtl') {
+            const physical = ['marginLeft', 'marginRight', 'paddingLeft', 'paddingRight', 'left', 'right'].filter(property => node.styles[property] !== undefined);
+            if (physical.length)
+                add('RTL_PHYSICAL_SPACING', 'advisory', [node.id], (evidence.directionSource === 'native-global' ? 'I18nManager reports global RTL; this node’s direction is unmeasured. ' : 'RTL layout uses ') + 'physical properties ' + physical.join(', ') + '. Confirm that physical, rather than logical, edges are intended.');
+        }
+    }
+    if (!snapshot.nodes.some(node => node.accessibility?.direction && node.accessibility.direction !== 'unknown'))
+        add('RTL_EVIDENCE', 'unavailable', [], 'Layout direction was not measured');
+    return findings;
+}

package/dist/core/design-intent.d.ts

@@ -0,0 +1,3 @@
+import { type DesignIntent, type DesignIntentResult } from '@nativemason/contracts';
+/** Compiles explicit design data. No image interpretation or app-state acceptance occurs here. */
+export declare function importDesignIntent(raw: DesignIntent): DesignIntentResult;

package/dist/core/design-intent.js

@@ -0,0 +1,108 @@
+import { BridgeFault, DesignIntentSchema, DesignIntentResultSchema, FigmaNodeSchema } from '@nativemason/contracts';
+const invalid = (message) => { throw new BridgeFault('INVALID_INPUT', message); };
+const referenced = (rule) => 'elementId' in rule ? [rule.elementId] : 'elementIds' in rule ? [...rule.elementIds] : [rule.first, rule.second];
+/** Compiles explicit design data. No image interpretation or app-state acceptance occurs here. */
+export function importDesignIntent(raw) {
+    const parsed = DesignIntentSchema.safeParse(raw);
+    if (!parsed.success)
+        invalid('Invalid design intent: ' + parsed.error.message);
+    const input = parsed.data, constraints = [], notes = [], required = new Set();
+    const { profile, tolerance } = input;
+    if (profile.root.width <= 0 || profile.root.height <= 0)
+        invalid('Design import requires a nonempty target app root');
+    const rectangle = (id, target) => {
+        if (required.has(id))
+            invalid('Duplicate mapped element: ' + id);
+        required.add(id);
+        constraints.push({ id: 'design:rect:' + encodeURIComponent(id), type: 'rect', elementId: id, target, tolerance });
+    };
+    if (input.kind === 'reference-annotations') {
+        const crop = input.appRootPixels, scale = input.pixelsPerLogicalUnit;
+        if (crop.x < 0 || crop.y < 0 || crop.x + crop.width > input.image.width || crop.y + crop.height > input.image.height)
+            invalid('App-root crop must fit the reference image');
+        if (Math.abs(crop.width - profile.root.width * scale) > 1 || Math.abs(crop.height - profile.root.height * scale) > 1)
+            invalid('Reference app-root crop and pixel scale disagree with the target profile');
+        for (const annotation of input.annotations) {
+            const box = annotation.rectPixels;
+            if (box.x < 0 || box.y < 0 || box.x + box.width > input.image.width || box.y + box.height > input.image.height)
+                invalid('Annotated rectangle must fit the reference image');
+            rectangle(annotation.elementId, { x: (box.x - crop.x) / scale, y: (box.y - crop.y) / scale, width: box.width / scale, height: box.height / scale });
+        }
+        constraints.push(...input.assertions);
+        for (const rule of input.assertions)
+            for (const id of referenced(rule))
+                required.add(id);
+        notes.push('Reference rectangles are agent-supplied annotations; the image hash records provenance, not semantic verification.');
+    }
+    else {
+        const frame = input.frame.absoluteBoundingBox, scale = input.logicalUnitsPerDesignUnit;
+        if (!frame || frame.width <= 0 || frame.height <= 0)
+            invalid('The selected Figma frame needs a nonempty absoluteBoundingBox');
+        const origin = frame;
+        if (Math.abs(origin.width * scale - profile.root.width) > tolerance || Math.abs(origin.height * scale - profile.root.height) > tolerance)
+            invalid('Figma frame scale must match the target app-root dimensions');
+        const mapped = new Map(Object.entries(input.elementMap)), values = [...mapped.values()];
+        if (!values.length || new Set(values).size !== values.length)
+            invalid('Figma mappings must use unique layout element IDs');
+        const nodes = new Map(), stack = [{ raw: input.frame, depth: 0 }];
+        while (stack.length) {
+            const item = stack.pop();
+            if (item.depth > 64 || nodes.size >= 10000)
+                invalid('Figma import exceeds the supported traversal limit');
+            const result = FigmaNodeSchema.safeParse(item.raw);
+            if (!result.success)
+                invalid('Malformed Figma node: ' + result.error.message);
+            const node = result.data;
+            if (nodes.has(node.id))
+                invalid('Duplicate Figma node ID: ' + node.id);
+            nodes.set(node.id, node);
+            for (const child of [...node.children ?? []].reverse())
+                stack.push({ raw: child, depth: item.depth + 1 });
+        }
+        for (const [figmaId, elementId] of mapped) {
+            const box = nodes.get(figmaId)?.absoluteBoundingBox;
+            if (!box)
+                invalid('Mapped Figma node is missing or has no bounds: ' + figmaId);
+            rectangle(elementId, { x: (box.x - origin.x) * scale, y: (box.y - origin.y) * scale, width: box.width * scale, height: box.height * scale });
+        }
+        for (const node of nodes.values()) {
+            if (node.layoutMode !== 'HORIZONTAL' && node.layoutMode !== 'VERTICAL')
+                continue;
+            if (node.layoutWrap === 'WRAP') {
+                notes.push('Wrapped Figma auto-layout requires reviewed row constraints: ' + node.id);
+                continue;
+            }
+            const axis = node.layoutMode === 'HORIZONTAL' ? 'x' : 'y', cross = axis === 'x' ? 'y' : 'x';
+            const children = (node.children ?? []).map(child => FigmaNodeSchema.parse(child));
+            const gap = node.itemSpacing;
+            const fixedGap = gap !== undefined && gap >= 0 && node.primaryAxisAlignItems !== 'SPACE_BETWEEN';
+            if (gap !== undefined && !fixedGap)
+                notes.push('Skipped negative/distributed Figma spacing: ' + node.id);
+            let run = [];
+            const align = () => {
+                const edge = node.counterAxisAlignItems === 'MIN' ? 'start' : node.counterAxisAlignItems === 'CENTER' ? 'center' : node.counterAxisAlignItems === 'MAX' ? 'end' : undefined;
+                if (run.length > 1 && edge)
+                    constraints.push({ id: 'design:align:' + encodeURIComponent(node.id) + ':' + encodeURIComponent(run[0]), type: 'align', axis: cross, edge, elementIds: [...run], tolerance });
+                run = [];
+            };
+            for (const child of children) {
+                const id = mapped.get(child.id);
+                if (!id || child.layoutPositioning === 'ABSOLUTE') {
+                    align();
+                    continue;
+                }
+                const previous = run.at(-1);
+                if (previous && fixedGap)
+                    constraints.push({ id: 'design:gap:' + encodeURIComponent(node.id) + ':' + encodeURIComponent(previous) + ':' + encodeURIComponent(id), type: 'gap', axis, first: previous, second: id, value: gap * scale, tolerance });
+                run.push(id);
+            }
+            align();
+            if (node.counterAxisAlignItems === 'BASELINE')
+                notes.push('Figma baseline alignment is not a supported geometric constraint: ' + node.id);
+        }
+        notes.push('Figma coordinates and auto-layout are design intent. Review the generated constraints against the app scenario.');
+    }
+    if (new Set(constraints.map(rule => rule.id)).size !== constraints.length)
+        invalid('Design import contains duplicate constraint IDs');
+    return DesignIntentResultSchema.parse({ source: input.kind, reviewRequired: true, notes, spec: { schemaVersion: 1, scenarioId: input.scenarioId, profile, requiredElementIds: [...required], constraints } });
+}

package/dist/core/index.d.ts

@@ -0,0 +1,15 @@
+import { type SuggestionCandidate, type InferenceOptions, type RuleFinding, type ConstraintResult, type DeviceProfile, type NormalizedPatch, type OverlayScene, type Rect, type Result, type SpatialDelta, type SpatialSnapshot, type WireframeSpec } from '@nativemason/contracts';
+/** Convert a window-space rectangle to root-space without applying insets twice. */
+export declare function normalizeRect(rect: Rect, root: Rect): Rect;
+export declare function safeAreaRect(profile: DeviceProfile): Rect;
+export declare function normalizePatch(patch: unknown): Result<NormalizedPatch>;
+export declare function profilesMatch(a: DeviceProfile, b: DeviceProfile): boolean;
+export declare function evaluateConstraints(snapshot: SpatialSnapshot, spec: WireframeSpec): readonly ConstraintResult[];
+export declare function diffSnapshots(before: SpatialSnapshot, after: SpatialSnapshot): SpatialDelta;
+export declare function buildOverlayScene(snapshot: SpatialSnapshot, spec: WireframeSpec): OverlayScene;
+/** Bounded deterministic proposals; trial evidence, never predicted acceptance. */
+export declare function generateFixCandidates(snapshot: SpatialSnapshot, spec: WireframeSpec, limit?: number): readonly SuggestionCandidate[];
+/** Produces an editable proposal, never an automatically accepted design specification. */
+export declare function inferConstraints(snapshot: SpatialSnapshot, options?: InferenceOptions): WireframeSpec;
+/** Advisory overlap and measured-box rules do not establish hit targets or design intent. */
+export declare function evaluateDefaultRules(snapshot: SpatialSnapshot): readonly RuleFinding[];

package/dist/core/index.js

@@ -0,0 +1,324 @@
+import { RnStylePatchSchema } from '@nativemason/contracts';
+/** Convert a window-space rectangle to root-space without applying insets twice. */
+export function normalizeRect(rect, root) {
+    return { ...rect, x: rect.x - root.x, y: rect.y - root.y };
+}
+export function safeAreaRect(profile) {
+    const { window: win, root, insets } = profile;
+    const left = Math.max(root.x, insets.left);
+    const top = Math.max(root.y, insets.top);
+    const right = Math.min(root.x + root.width, win.width - insets.right);
+    const bottom = Math.min(root.y + root.height, win.height - insets.bottom);
+    return { x: left - root.x, y: top - root.y, width: Math.max(0, right - left), height: Math.max(0, bottom - top) };
+}
+export function normalizePatch(patch) {
+    const parsed = RnStylePatchSchema.safeParse(patch);
+    return parsed.success ? { ok: true, value: Object.freeze(parsed.data) } : {
+        ok: false, error: { code: 'INVALID_INPUT', message: parsed.error.message },
+    };
+}
+function idsFor(rule) {
+    switch (rule.type) {
+        case 'textFits':
+        case 'rect':
+        case 'minTouchTarget':
+        case 'insideSafeArea': return [rule.elementId];
+        case 'align': return rule.elementIds;
+        default: return [rule.first, rule.second];
+    }
+}
+function axisValue(rect, axis, edge) {
+    const size = axis === 'x' ? rect.width : rect.height;
+    return rect[axis] + (edge === 'start' ? 0 : edge === 'center' ? size / 2 : size);
+}
+function deviation(rule, rects, profile) {
+    const [a, b] = rects;
+    switch (rule.type) {
+        case 'textFits': return 0;
+        case 'rect': return Math.max(...['x', 'y', 'width', 'height'].map(k => Math.abs(a[k] - rule.target[k])));
+        case 'minTouchTarget': return Math.max(0, rule.width - a.width, rule.height - a.height);
+        case 'align': {
+            const values = rects.map(r => axisValue(r, rule.axis, rule.edge));
+            return Math.max(...values) - Math.min(...values);
+        }
+        case 'gap': return Math.abs(axisValue(b, rule.axis, 'start') - axisValue(a, rule.axis, 'end') - rule.value);
+        case 'insideSafeArea': {
+            const safe = safeAreaRect(profile);
+            return Math.max(0, safe.x - a.x, safe.y - a.y, a.x + a.width - safe.x - safe.width, a.y + a.height - safe.y - safe.height);
+        }
+        case 'disjoint': {
+            if (a.width === 0 || a.height === 0 || b.width === 0 || b.height === 0)
+                return 0;
+            const overlapX = Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x);
+            const overlapY = Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y);
+            return Math.max(0, Math.min(overlapX, overlapY));
+        }
+    }
+}
+export function profilesMatch(a, b) {
+    return a.orientation === b.orientation && a.fontScale === b.fontScale && a.pixelRatio === b.pixelRatio &&
+        Math.abs(a.window.width - b.window.width) <= 0.01 && Math.abs(a.window.height - b.window.height) <= 0.01 &&
+        ['x', 'y', 'width', 'height'].every(k => Math.abs(a.root[k] - b.root[k]) <= 0.01) &&
+        ['top', 'right', 'bottom', 'left'].every(k => Math.abs(a.insets[k] - b.insets[k]) <= 0.01);
+}
+export function evaluateConstraints(snapshot, spec) {
+    const nodes = new Map(snapshot.nodes.map(n => [n.id, n]));
+    const duplicates = nodes.size !== snapshot.nodes.length;
+    const contextMatches = snapshot.scenarioId === spec.scenarioId && profilesMatch(snapshot.profile, spec.profile) && snapshot.status === 'stable' && !duplicates;
+    const results = spec.requiredElementIds.filter(id => !nodes.has(id)).map(id => ({
+        constraintId: `required:${id}`, status: 'unavailable', elementIds: [id], deviation: null, tolerance: 0, message: `Required element ${id} is missing`,
+    }));
+    if (!contextMatches)
+        results.push({ constraintId: 'capture-context', status: 'unavailable', elementIds: [], deviation: null, tolerance: 0, message: 'Scenario, profile, unique IDs and stable capture must match the specification' });
+    for (const rule of spec.constraints) {
+        const ids = idsFor(rule);
+        if (!contextMatches || ids.some(id => !nodes.has(id))) {
+            results.push({ constraintId: rule.id, status: 'unavailable', elementIds: ids, deviation: null, tolerance: rule.tolerance, message: 'Required element or matching stable capture unavailable' });
+            continue;
+        }
+        if (rule.type === 'textFits') {
+            const node = nodes.get(rule.elementId);
+            const evidence = node.textFit;
+            const tolerance = rule.pixelAware ? Math.max(rule.tolerance, 2 / snapshot.profile.pixelRatio) : rule.tolerance;
+            if (!evidence || evidence.status !== 'supported' || evidence.fullLineCount === undefined || evidence.fullHeight === undefined || evidence.availableHeight === undefined) {
+                results.push({ constraintId: rule.id, status: 'unavailable', elementIds: ids, deviation: null, tolerance, message: evidence?.reason ?? 'Equivalent unconstrained text measurement unavailable' });
+            }
+            else {
+                const overflow = Math.max(0, evidence.fullHeight - evidence.availableHeight);
+                const lineLimit = node.authoredTextProps?.numberOfLines;
+                const tooManyLines = lineLimit !== undefined && evidence.fullLineCount > lineLimit;
+                const passed = !tooManyLines && overflow <= tolerance;
+                results.push({ constraintId: rule.id, status: passed ? 'pass' : 'fail', elementIds: ids, deviation: overflow, tolerance, message: passed ? 'Unconstrained text fits the measured box and line limit' : tooManyLines ? `Full text requires ${evidence.fullLineCount} lines, exceeding the authored limit ${lineLimit}` : `Full text exceeds available height by ${overflow} logical units` });
+            }
+            continue;
+        }
+        const amount = deviation(rule, ids.map(id => nodes.get(id).rect), snapshot.profile);
+        const tolerance = rule.pixelAware ? Math.max(rule.tolerance, 2 / snapshot.profile.pixelRatio) : rule.tolerance;
+        results.push({ constraintId: rule.id, status: amount <= tolerance ? 'pass' : 'fail', elementIds: ids, deviation: amount, tolerance, message: amount <= tolerance ? 'Within tolerance' : `Deviation ${amount} exceeds tolerance ${tolerance}` });
+    }
+    return results;
+}
+export function diffSnapshots(before, after) {
+    const old = new Map(before.nodes.map(n => [n.id, n]));
+    const next = new Map(after.nodes.map(n => [n.id, n]));
+    return {
+        added: [...next.keys()].filter(id => !old.has(id)).sort(),
+        removed: [...old.keys()].filter(id => !next.has(id)).sort(),
+        changed: [...next.keys()].filter(id => old.has(id)).sort().flatMap(id => {
+            const a = old.get(id).rect, b = next.get(id).rect;
+            if (['x', 'y', 'width', 'height'].every(k => a[k] === b[k]))
+                return [];
+            return [{ id, before: { ...a }, after: { ...b }, delta: { x: b.x - a.x, y: b.y - a.y, width: b.width - a.width, height: b.height - a.height } }];
+        }),
+    };
+}
+export function buildOverlayScene(snapshot, spec) {
+    return {
+        width: snapshot.profile.window.width, height: snapshot.profile.window.height,
+        marks: [...snapshot.nodes].sort((a, b) => a.id.localeCompare(b.id)).map((n, i) => ({ label: i + 1, id: n.id, rect: { ...n.rect, x: n.rect.x + snapshot.profile.root.x, y: n.rect.y + snapshot.profile.root.y } })),
+        targets: spec.constraints.flatMap(c => c.type === 'rect' ? [{ id: c.elementId, rect: { ...c.target, x: c.target.x + snapshot.profile.root.x, y: c.target.y + snapshot.profile.root.y } }] : []),
+    };
+}
+/** Bounded deterministic proposals; trial evidence, never predicted acceptance. */
+export function generateFixCandidates(snapshot, spec, limit = 12) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw new Error('Candidate limit must be an integer from 1 to 100');
+    const nodes = new Map(snapshot.nodes.map(node => [node.id, node]));
+    const failed = new Set(evaluateConstraints(snapshot, spec).filter(result => result.status === 'fail').map(result => result.constraintId));
+    const candidates = [];
+    const seen = new Map();
+    const add = (candidate) => {
+        if (!candidate.mutations.length || candidate.mutations.some(mutation => !nodes.get(mutation.elementId)?.editable || !RnStylePatchSchema.safeParse(mutation.patch).success))
+            return;
+        const key = JSON.stringify(candidate.mutations), existing = seen.get(key);
+        if (existing !== undefined) {
+            candidates[existing].constraintIds = [...new Set([...candidates[existing].constraintIds, ...candidate.constraintIds])];
+            return;
+        }
+        seen.set(key, candidates.length);
+        candidates.push(candidate);
+    };
+    const numeric = (value, fallback = 0) => typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+    const margin = (node, axis) => numeric(node.styles[axis === 'x' ? 'marginLeft' : 'marginTop'], numeric(node.styles[axis === 'x' ? 'marginHorizontal' : 'marginVertical'], numeric(node.styles.margin)));
+    const offerWrapping = (parent, constraintId) => {
+        if (!parent?.editable || !String(parent.styles.flexDirection ?? 'column').startsWith('row') || parent.rect.width <= 0)
+            return;
+        const children = snapshot.nodes.filter(node => node.parentId === parent.id);
+        const padding = numeric(parent.styles.paddingLeft, numeric(parent.styles.paddingHorizontal, numeric(parent.styles.padding))) + numeric(parent.styles.paddingRight, numeric(parent.styles.paddingHorizontal, numeric(parent.styles.padding)));
+        const availableWidth = Math.max(0, parent.rect.width - padding);
+        const gap = numeric(parent.styles.columnGap, numeric(parent.styles.gap));
+        const totalWidth = children.reduce((total, child) => total + child.rect.width, 0) + Math.max(0, children.length - 1) * gap;
+        if (children.length > 1 && totalWidth > availableWidth)
+            add({ mutations: [{ elementId: parent.id, patch: { flexWrap: 'wrap' } }], reason: 'Trial sibling wrapping where measured row contents exceed the available parent width', constraintIds: [constraintId] });
+    };
+    for (const rule of spec.constraints) {
+        if (!failed.has(rule.id))
+            continue;
+        const selected = idsFor(rule).map(id => nodes.get(id));
+        if (selected.some(node => !node))
+            continue;
+        const members = selected;
+        const parentId = members[0].parentId;
+        const parent = parentId && members.every(node => node.parentId === parentId) ? nodes.get(parentId) : undefined;
+        const [first, second] = members;
+        if (rule.type === 'minTouchTarget' && first.editable) {
+            const patch = { minWidth: Math.max(numeric(first.styles.minWidth), rule.width), minHeight: Math.max(numeric(first.styles.minHeight), rule.height), ...(typeof first.styles.maxWidth === 'number' && first.styles.maxWidth < rule.width ? { maxWidth: rule.width } : {}), ...(typeof first.styles.maxHeight === 'number' && first.styles.maxHeight < rule.height ? { maxHeight: rule.height } : {}) };
+            add({ mutations: [{ elementId: first.id, patch }], reason: 'Increase measured layout-box minimum dimensions; effective touchability still needs separate evidence', constraintIds: [rule.id] });
+        }
+        else if (rule.type === 'insideSafeArea') {
+            const safe = safeAreaRect(snapshot.profile);
+            if (first.editable && safe.width > 0 && safe.height > 0) {
+                const width = Math.min(first.rect.width, safe.width), height = Math.min(first.rect.height, safe.height);
+                const targetX = Math.max(safe.x, Math.min(first.rect.x, safe.x + safe.width - width));
+                const targetY = Math.max(safe.y, Math.min(first.rect.y, safe.y + safe.height - height));
+                const dx = targetX - first.rect.x, dy = targetY - first.rect.y;
+                add({ mutations: [{ elementId: first.id, patch: { ...(first.rect.width > safe.width ? { width: safe.width } : {}), ...(first.rect.height > safe.height ? { height: safe.height } : {}), ...(dx !== 0 ? { marginLeft: margin(first, 'x') + dx } : {}), ...(dy !== 0 ? { marginTop: margin(first, 'y') + dy } : {}) } }], reason: 'Trial measured box bounds and spacing within the root-relative safe area', constraintIds: [rule.id] });
+            }
+            offerWrapping(parent || undefined, rule.id);
+        }
+        else if (rule.type === 'disjoint') {
+            if (parent?.editable)
+                for (const direction of ['row', 'column'])
+                    add({ mutations: [{ elementId: parent.id, patch: { flexDirection: direction, gap: Math.max(0, numeric(parent.styles.gap)) } }], reason: 'Trial non-overlapping sibling flow for an explicit disjoint constraint', constraintIds: [rule.id] });
+            if (second.editable)
+                for (const axis of ['x', 'y']) {
+                    const property = axis === 'x' ? 'marginLeft' : 'marginTop';
+                    const shift = axisValue(first.rect, axis, 'end') - axisValue(second.rect, axis, 'start');
+                    if (shift > 0)
+                        add({ mutations: [{ elementId: second.id, patch: { [property]: margin(second, axis) + shift } }], reason: 'Move the second measured box beyond the first on one axis; trial checks regressions', constraintIds: [rule.id] });
+                }
+            offerWrapping(parent || undefined, rule.id);
+        }
+        else if (rule.type === 'textFits') {
+            // A failing textFits result already requires supported, equivalent full-text evidence.
+            // We never infer an authored numberOfLines prop or fabricate font metrics.
+            const evidence = first.textFit;
+            if (first.editable) {
+                if (evidence.fullHeight > evidence.availableHeight)
+                    add({ mutations: [{ elementId: first.id, patch: { height: evidence.fullHeight, minHeight: evidence.fullHeight } }], reason: 'Trial enough box height for the measured unconstrained text; authored line limits remain unchanged', constraintIds: [rule.id] });
+                if (parent && parent.rect.width > first.rect.width)
+                    add({ mutations: [{ elementId: first.id, patch: { width: parent.rect.width, flexShrink: 0 } }], reason: 'Trial additional measured parent width to reduce text wrapping without shrinking the font', constraintIds: [rule.id] });
+                if (numeric(first.styles.flexShrink) > 0)
+                    add({ mutations: [{ elementId: first.id, patch: { flexShrink: 0 } }], reason: 'Trial preserving text width instead of allowing sibling flex shrink', constraintIds: [rule.id] });
+            }
+            offerWrapping(parent || undefined, rule.id);
+        }
+        else if (rule.type === 'rect' && first.editable) {
+            add({ mutations: [{ elementId: first.id, patch: { width: rule.target.width, height: rule.target.height, ...(first.rect.x !== rule.target.x ? { marginLeft: margin(first, 'x') + rule.target.x - first.rect.x } : {}), ...(first.rect.y !== rule.target.y ? { marginTop: margin(first, 'y') + rule.target.y - first.rect.y } : {}) } }], reason: 'Trial explicit target dimensions and measured spacing correction', constraintIds: [rule.id] });
+            offerWrapping(parent || undefined, rule.id);
+        }
+        else if (rule.type === 'gap') {
+            if (parent?.editable) {
+                const property = rule.axis === 'x' ? 'columnGap' : 'rowGap';
+                add({ mutations: [{ elementId: parent.id, patch: { [property]: rule.value } }], reason: 'Set the shared parent spacing on the requested axis', constraintIds: [rule.id] });
+                add({ mutations: [{ elementId: parent.id, patch: { flexDirection: rule.axis === 'x' ? 'row' : 'column', [property]: rule.value } }], reason: 'Arrange siblings on the requested axis with explicit spacing', constraintIds: [rule.id] });
+            }
+            if (second.editable) {
+                const property = rule.axis === 'x' ? 'marginLeft' : 'marginTop';
+                const correction = axisValue(first.rect, rule.axis, 'end') + rule.value - axisValue(second.rect, rule.axis, 'start');
+                add({ mutations: [{ elementId: second.id, patch: { [property]: margin(second, rule.axis) + correction } }], reason: 'Adjust the second element spacing by the measured gap error', constraintIds: [rule.id] });
+            }
+            offerWrapping(parent || undefined, rule.id);
+        }
+        else if (rule.type === 'align') {
+            const alignment = rule.edge === 'start' ? 'flex-start' : rule.edge === 'end' ? 'flex-end' : 'center';
+            const crossAxis = parent && (String(parent.styles.flexDirection ?? 'column').startsWith('row') ? 'y' : 'x');
+            if (parent?.editable && crossAxis === rule.axis)
+                add({ mutations: [{ elementId: parent.id, patch: { alignItems: alignment } }], reason: 'Align siblings along their parent cross axis', constraintIds: [rule.id] });
+            if (parent?.editable && crossAxis !== rule.axis)
+                add({ mutations: [{ elementId: parent.id, patch: { flexDirection: rule.axis === 'y' ? 'row' : 'column', alignItems: alignment } }], reason: 'Arrange siblings so the requested alignment is on the parent cross axis', constraintIds: [rule.id] });
+            const mutations = members.filter(node => node.editable).map(node => ({ elementId: node.id, patch: { alignSelf: alignment } }));
+            if (mutations.length && crossAxis === rule.axis)
+                add({ mutations, reason: 'Align the selected siblings without changing the parent default', constraintIds: [rule.id] });
+            offerWrapping(parent || undefined, rule.id);
+        }
+        if (candidates.length >= limit)
+            break;
+    }
+    return candidates.slice(0, limit);
+}
+/** Produces an editable proposal, never an automatically accepted design specification. */
+export function inferConstraints(snapshot, options = {}) {
+    const tolerance = options.tolerance ?? 2;
+    if (!Number.isFinite(tolerance) || tolerance < 0)
+        throw new Error('Inference tolerance must be finite and nonnegative');
+    if (snapshot.status !== 'stable' || new Set(snapshot.nodes.map(node => node.id)).size !== snapshot.nodes.length)
+        throw new Error('Inference requires a stable snapshot with unique element IDs');
+    const constraints = [];
+    const ordered = [...snapshot.nodes].sort((a, b) => a.id.localeCompare(b.id));
+    const safe = safeAreaRect(snapshot.profile);
+    for (const node of ordered) {
+        const id = encodeURIComponent(node.id);
+        if (options.includeRectangles !== false)
+            constraints.push({ id: `inferred:rect:${id}`, type: 'rect', elementId: node.id, target: { ...node.rect }, tolerance });
+        if (node.rect.x >= safe.x && node.rect.y >= safe.y && node.rect.x + node.rect.width <= safe.x + safe.width && node.rect.y + node.rect.height <= safe.y + safe.height)
+            constraints.push({ id: `inferred:safe:${id}`, type: 'insideSafeArea', elementId: node.id, tolerance });
+    }
+    const groups = new Map();
+    for (const node of ordered) {
+        const group = groups.get(node.parentId) ?? [];
+        group.push(node);
+        groups.set(node.parentId, group);
+    }
+    for (const group of groups.values())
+        for (const axis of ['x', 'y']) {
+            for (const edge of ['start', 'center', 'end']) {
+                const sorted = [...group].sort((a, b) => axisValue(a.rect, axis, edge) - axisValue(b.rect, axis, edge) || a.id.localeCompare(b.id));
+                let cluster = [];
+                const flush = () => { if (cluster.length > 1)
+                    constraints.push({ id: `inferred:align:${axis}:${edge}:${cluster.map(n => encodeURIComponent(n.id)).join(':')}`, type: 'align', axis, edge, elementIds: cluster.map(n => n.id), tolerance }); };
+                for (const node of sorted) {
+                    if (cluster.length && axisValue(node.rect, axis, edge) - axisValue(cluster[0].rect, axis, edge) > tolerance) {
+                        flush();
+                        cluster = [];
+                    }
+                    cluster.push(node);
+                }
+                flush();
+            }
+            const sorted = [...group].sort((a, b) => a.rect[axis] - b.rect[axis] || a.id.localeCompare(b.id));
+            for (let i = 1; i < sorted.length; i++) {
+                const a = sorted[i - 1], b = sorted[i], cross = axis === 'x' ? 'y' : 'x', size = cross === 'x' ? 'width' : 'height';
+                const gap = axisValue(b.rect, axis, 'start') - axisValue(a.rect, axis, 'end');
+                const crossOverlap = Math.min(a.rect[cross] + a.rect[size], b.rect[cross] + b.rect[size]) - Math.max(a.rect[cross], b.rect[cross]);
+                if (gap >= 0 && crossOverlap > 0)
+                    constraints.push({ id: `inferred:gap:${axis}:${encodeURIComponent(a.id)}:${encodeURIComponent(b.id)}`, type: 'gap', axis, first: a.id, second: b.id, value: gap, tolerance });
+            }
+        }
+    return { schemaVersion: 1, scenarioId: snapshot.scenarioId, profile: structuredClone(snapshot.profile), requiredElementIds: ordered.map(node => node.id), constraints };
+}
+/** Advisory overlap and measured-box rules do not establish hit targets or design intent. */
+export function evaluateDefaultRules(snapshot) {
+    const findings = [];
+    if (snapshot.status !== 'stable')
+        return [{ code: 'UNSTABLE_LAYOUT', severity: 'unavailable', elementIds: [], message: 'Default rules require a settled capture' }];
+    const minimum = snapshot.platform === 'ios' ? 44 : 48;
+    const safe = safeAreaRect(snapshot.profile);
+    const ordered = [...snapshot.nodes].sort((a, b) => a.id.localeCompare(b.id));
+    for (const node of ordered) {
+        if ((node.kind === 'Pressable' || node.role === 'button') && (node.rect.width < minimum || node.rect.height < minimum))
+            findings.push({ code: 'MINIMUM_LAYOUT_BOX', severity: 'confirmed', elementIds: [node.id], message: `Measured box is ${node.rect.width} × ${node.rect.height}; recommended minimum is ${minimum} × ${minimum}. This does not measure effective touchability.` });
+        if (node.parentId !== null && (node.rect.x < safe.x - 2 || node.rect.y < safe.y - 2 || node.rect.x + node.rect.width > safe.x + safe.width + 2 || node.rect.y + node.rect.height > safe.y + safe.height + 2))
+            findings.push({ code: 'SAFE_AREA', severity: 'advisory', elementIds: [node.id], message: 'Measured element extends outside the safe area; confirm whether edge-to-edge rendering is intentional' });
+    }
+    for (let i = 0; i < ordered.length; i++)
+        for (let j = i + 1; j < ordered.length; j++) {
+            const a = ordered[i], b = ordered[j];
+            if (a.parentId === null || a.parentId !== b.parentId)
+                continue;
+            const x = Math.min(a.rect.x + a.rect.width, b.rect.x + b.rect.width) - Math.max(a.rect.x, b.rect.x);
+            const y = Math.min(a.rect.y + a.rect.height, b.rect.y + b.rect.height) - Math.max(a.rect.y, b.rect.y);
+            if (x > 2 && y > 2)
+                findings.push({ code: 'SIBLING_OVERLAP', severity: 'advisory', elementIds: [a.id, b.id], message: 'Sibling rectangles overlap; explicit disjoint constraints are required to classify intentional layering as a violation' });
+        }
+    if (snapshot.platform === 'web') {
+        if (!snapshot.webDiagnostics)
+            findings.push({ code: 'CLIPPING_EVIDENCE', severity: 'unavailable', elementIds: [], message: 'Browser clipping diagnostics are unavailable' });
+        else
+            for (const warning of snapshot.webDiagnostics.warnings)
+                findings.push({ code: warning.code, severity: warning.severity === 'confirmed' ? 'confirmed' : 'unavailable', elementIds: [warning.elementId], message: warning.message });
+    }
+    else
+        findings.push({ code: 'CLIPPING_EVIDENCE', severity: 'unavailable', elementIds: [], message: 'Native clipping is not established by the registered layout boxes' });
+    return findings;
+}

package/dist/editor/index.d.ts

@@ -0,0 +1,4 @@
+export { planSourcePatch, hashSource } from './planner.js';
+export { planTransaction } from './transaction-planner.js';
+export { createSourcePort } from './source-port.js';
+export { createTransactionSourcePort } from './transaction-port.js';

package/dist/editor/index.js

@@ -0,0 +1,4 @@
+export { planSourcePatch, hashSource } from './planner.js';
+export { planTransaction } from './transaction-planner.js';
+export { createSourcePort } from './source-port.js';
+export { createTransactionSourcePort } from './transaction-port.js';

package/dist/editor/planner.d.ts

@@ -0,0 +1,4 @@
+import { type EditPlan, type Result, type RnStylePatch, type SourceRef, type EditScope } from '@nativemason/contracts';
+export declare const hashSource: (text: string) => string;
+/** Pure planning: parses in memory and returns text; never writes the source tree. */
+export declare function planSourcePatch(sourceText: string, sourceRef: SourceRef, patch: RnStylePatch, scope?: EditScope): Result<EditPlan>;