@hoilab/ada-cli 0.84.21 → 0.85.0

package/dist/core/computer/motor/outline.js

@@ -0,0 +1,590 @@
+const DEFAULT_BUDGET = { maxDepth: 2, maxNodes: 150 };
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function comoTexto(value) {
+    return typeof value === "string" ? value : "";
+}
+function toNumber(value, fallback = 0) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string") {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return fallback;
+}
+function toBoolean(value) {
+    return value === true;
+}
+function parseRect(raw) {
+    const rect = isRecord(raw) ? raw : {};
+    return {
+        x: toNumber(rect.x),
+        y: toNumber(rect.y),
+        w: Math.max(0, toNumber(rect.w)),
+        h: Math.max(0, toNumber(rect.h)),
+    };
+}
+function parseText(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .map((item) => {
+        if (!isRecord(item))
+            return undefined;
+        const string = comoTexto(item.string);
+        if (!string)
+            return undefined;
+        return {
+            string,
+            confidence: Math.max(0, Math.min(1, toNumber(item.confidence))),
+            rect: parseRect(item.rect),
+        };
+    })
+        .filter((item) => Boolean(item));
+}
+function parseNode(raw, parent) {
+    const record = isRecord(raw) ? raw : {};
+    const wireRef = comoTexto(record.ref) || undefined;
+    const node = {
+        ref: "",
+        wireRef,
+        role: comoTexto(record.role),
+        subrole: comoTexto(record.subrole),
+        identifier: comoTexto(record.identifier),
+        title: comoTexto(record.title),
+        description: comoTexto(record.description),
+        value: comoTexto(record.value),
+        actions: Array.isArray(record.actions)
+            ? record.actions.filter((value) => typeof value === "string")
+            : [],
+        canPress: toBoolean(record.canPress),
+        canFocus: toBoolean(record.canFocus),
+        canSetValue: toBoolean(record.canSetValue),
+        canScroll: toBoolean(record.canScroll),
+        canIncrement: toBoolean(record.canIncrement),
+        canDecrement: toBoolean(record.canDecrement),
+        isTextInput: toBoolean(record.isTextInput),
+        rect: parseRect(record.rect),
+        focused: toBoolean(record.focused),
+        offscreen: toBoolean(record.offscreen),
+        pictureOnly: toBoolean(record.pictureOnly),
+        truncated: toBoolean(record.truncated),
+        scrollExtent: isRecord(record.scrollExtent)
+            ? {
+                seen: Math.max(0, Math.trunc(toNumber(record.scrollExtent.seen))),
+                total: Math.max(0, Math.trunc(toNumber(record.scrollExtent.total))),
+            }
+            : undefined,
+        text: parseText(record.text),
+        children: [],
+        parent,
+    };
+    node.children = (Array.isArray(record.children) ? record.children : []).map((child) => parseNode(child, node));
+    return node;
+}
+export function parseLookResponse(raw) {
+    const record = isRecord(raw) ? raw : {};
+    const image = isRecord(record.image) ? record.image : undefined;
+    const window = isRecord(record.window) ? record.window : {};
+    const metadata = isRecord(window.metadata) ? window.metadata : undefined;
+    const outline = buildOutline(comoTexto(record.lookId), parseNode(record.outline));
+    const readText = isRecord(record.readText) ? record.readText : undefined;
+    const requestedReadText = readText?.requested === "auto" || readText?.requested === "always" || readText?.requested === "never"
+        ? readText.requested
+        : undefined;
+    const look = {
+        lookId: comoTexto(record.lookId),
+        capturedAt: toNumber(record.capturedAt, Date.now() / 1000),
+        window: {
+            windowId: Math.trunc(toNumber(window.windowId)),
+            rootRef: comoTexto(window.rootRef) || undefined,
+            kind: comoTexto(window.kind) || undefined,
+            framePoints: parseRect(window.framePoints),
+            scaleFactor: Math.max(1, toNumber(window.scaleFactor, 1)),
+            isModal: toBoolean(window.isModal),
+            metadata,
+            role: comoTexto(window.role),
+            subrole: comoTexto(window.subrole),
+        },
+        image: image
+            ? {
+                jpegBase64: comoTexto(image.jpegBase64),
+                mimeType: image.mimeType === "image/png" ? "image/png" : "image/jpeg",
+                width: Math.max(1, Math.trunc(toNumber(image.width, 1))),
+                height: Math.max(1, Math.trunc(toNumber(image.height, 1))),
+            }
+            : undefined,
+        outline: outline.root,
+        timings: isRecord(record.timings)
+            ? Object.fromEntries(Object.entries(record.timings).map(([key, value]) => [key, toNumber(value)]))
+            : {},
+        readText: readText ? { requested: requestedReadText, executed: toBoolean(readText.executed) } : undefined,
+        parsedOutline: outline,
+    };
+    if (!look.lookId)
+        throw new Error("Helper returned a look without lookId.");
+    return look;
+}
+function buildOutline(lookId, root) {
+    const nodes = [];
+    const refToWireRef = new Map();
+    const wireRefToRef = new Map();
+    const queue = [root];
+    let index = 0;
+    while (index < queue.length) {
+        const node = queue[index++];
+        node.ref = `@e${nodes.length + 1}`;
+        nodes.push(node);
+        if (node.wireRef) {
+            refToWireRef.set(node.ref, node.wireRef);
+            wireRefToRef.set(node.wireRef, node.ref);
+        }
+        queue.push(...node.children);
+    }
+    return { lookId, root, nodes, refToWireRef, wireRefToRef };
+}
+export function nodeByRef(outline, ref) {
+    return outline.nodes.find((node) => node.ref === ref || node.wireRef === ref);
+}
+export function outlineNodeLabel(node) {
+    return (node.title ||
+        node.description ||
+        node.value ||
+        node.identifier ||
+        node.text
+            .map((item) => item.string)
+            .join(" ")
+            .trim());
+}
+function displayName(node) {
+    const label = outlineNodeLabel(node);
+    return `${node.role || "AXUnknown"}${node.subrole ? `/${node.subrole}` : ""}${label ? ` ${JSON.stringify(label)}` : ""}`;
+}
+export function outlineNodePath(node) {
+    const parts = [];
+    let current = node;
+    while (current) {
+        parts.unshift(displayName(current));
+        current = current.parent;
+    }
+    return parts.join(" ▸ ");
+}
+function countDescendants(node) {
+    const roles = new Map();
+    let total = 0;
+    let pictureOnly = 0;
+    const visit = (current) => {
+        for (const child of current.children) {
+            total += 1;
+            if (child.pictureOnly)
+                pictureOnly += 1;
+            const role = child.pictureOnly ? "picture-only" : roleName(child.role);
+            roles.set(role, (roles.get(role) ?? 0) + 1);
+            visit(child);
+        }
+    };
+    visit(node);
+    return { total, roles, pictureOnly };
+}
+function roleName(role) {
+    const stripped = role.replace(/^AX/, "").toLowerCase();
+    return stripped || "nodes";
+}
+function plural(count, singular) {
+    if (singular === "picture-only")
+        return "picture-only";
+    return `${singular}${count === 1 ? "" : "s"}`;
+}
+function foldedSummary(node) {
+    const counts = countDescendants(node);
+    const roleCounts = [...counts.roles.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, 4)
+        .map(([role, count]) => `${count} ${plural(count, role)}`);
+    const countText = `${counts.total}: ${roleCounts.join(", ") || "0 children"}`;
+    const scroll = node.scrollExtent ? ` [scrollable ${node.scrollExtent.seen}/${node.scrollExtent.total}]` : "";
+    return ` ▸ (${countText})${scroll}`;
+}
+function annotationText(node) {
+    const annotations = [
+        node.offscreen ? "offscreen" : undefined,
+        node.pictureOnly ? "pictureOnly" : undefined,
+        node.truncated ? "truncated" : undefined,
+        node.scrollExtent ? `scrollable ${node.scrollExtent.seen}/${node.scrollExtent.total}` : undefined,
+    ].filter((item) => Boolean(item));
+    return annotations.length ? ` [${annotations.join(", ")}]` : "";
+}
+function lineForNode(node, depth, folded) {
+    const actions = node.actions.length ? ` {${node.actions.join(",")}}` : "";
+    return `${"  ".repeat(depth)}${node.ref} ${displayName(node)}${actions}${annotationText(node)}${folded ? foldedSummary(node) : ""}`;
+}
+function pathRefs(node) {
+    const refs = [];
+    let current = node;
+    while (current) {
+        refs.unshift(current.ref);
+        current = current.parent;
+    }
+    return refs;
+}
+function defaultUnfoldRefs(outline) {
+    const refs = new Set([outline.root.ref]);
+    for (const node of outline.nodes) {
+        if (node.truncated || node.parent?.role === "AXSheet" || node.role === "AXSheet" || node.role === "AXDialog") {
+            for (const ref of pathRefs(node))
+                refs.add(ref);
+        }
+        if (node.focused) {
+            for (const ref of pathRefs(node))
+                refs.add(ref);
+            for (const child of node.children)
+                refs.add(child.ref);
+        }
+    }
+    return refs;
+}
+export function foldToBudget(outline, budget = {}, unfoldPaths = []) {
+    const maxDepth = Math.max(0, Math.trunc(budget.maxDepth ?? DEFAULT_BUDGET.maxDepth));
+    const maxNodes = Math.max(1, Math.trunc(budget.maxNodes ?? DEFAULT_BUDGET.maxNodes));
+    const unfolded = defaultUnfoldRefs(outline);
+    for (const ref of unfoldPaths) {
+        const node = nodeByRef(outline, ref);
+        if (!node)
+            continue;
+        for (const pathRef of pathRefs(node))
+            unfolded.add(pathRef);
+        for (const child of node.children)
+            unfolded.add(child.ref);
+    }
+    const lines = [];
+    const renderedRefs = [];
+    let truncated = false;
+    const render = (node, depth) => {
+        if (lines.length >= maxNodes) {
+            truncated = true;
+            return;
+        }
+        const shouldUnfold = depth < maxDepth || unfolded.has(node.ref);
+        const folded = node.children.length > 0 && !shouldUnfold;
+        lines.push(lineForNode(node, depth, folded));
+        renderedRefs.push(node.ref);
+        if (folded)
+            return;
+        for (const child of node.children)
+            render(child, depth + 1);
+    };
+    render(outline.root, 0);
+    if (truncated) {
+        const remaining = Math.max(0, outline.nodes.length - renderedRefs.length);
+        lines.push(`… render budget reached: ${remaining} more nodes not shown; use search_ui or expand_ui(@eN)`);
+    }
+    return {
+        text: lines.join("\n"),
+        renderedRefs,
+        nodeCount: outline.nodes.length,
+        fullUnfoldLineCount: outline.nodes.length,
+        truncated,
+    };
+}
+function actionMatches(node, action) {
+    const query = action.toLowerCase();
+    if (query === "press" && node.canPress)
+        return true;
+    if (query === "focus" && node.canFocus)
+        return true;
+    if ((query === "setvalue" || query === "set_text" || query === "settext") && node.canSetValue)
+        return true;
+    if (query === "scroll" && node.canScroll)
+        return true;
+    if (query === "increment" && node.canIncrement)
+        return true;
+    if (query === "decrement" && node.canDecrement)
+        return true;
+    return node.actions.some((candidate) => candidate.toLowerCase().includes(query));
+}
+function normalizedSearchRole(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/^ax/, "")
+        .replace(/[ _-]+/g, "");
+}
+function damerauLevenshtein(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    const matrix = Array.from({ length: rows }, (_, i) => Array.from({ length: cols }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i < rows; i += 1) {
+        for (let j = 1; j < cols; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+                matrix[i][j] = Math.min(matrix[i][j], matrix[i - 2][j - 2] + 1);
+        }
+    }
+    return matrix[a.length][b.length];
+}
+export function rankedTextMatch(values, text) {
+    const query = text.toLowerCase().replace(/\s+/g, " ").trim().slice(0, 256);
+    if (!query)
+        return undefined;
+    const candidates = values
+        .map((value) => value.toLowerCase().replace(/\s+/g, " ").trim().slice(0, 512))
+        .filter(Boolean);
+    if (candidates.some((value) => value === query))
+        return { reason: "exact", score: 1 };
+    if (candidates.some((value) => value.startsWith(query) || value.split(/\W+/).some((token) => token.startsWith(query))))
+        return { reason: "prefix", score: 0.95 };
+    if (candidates.some((value) => value.includes(query)))
+        return { reason: "substring", score: 0.9 };
+    let score = 0;
+    for (const value of candidates) {
+        for (const candidate of [value, ...value.split(/\W+/)]) {
+            if (!candidate || candidate.length > 256)
+                continue;
+            score = Math.max(score, 1 - damerauLevenshtein(query, candidate) / Math.max(query.length, candidate.length));
+        }
+    }
+    return score >= 0.72 ? { reason: "fuzzy", score } : undefined;
+}
+export function searchOutlineRanked(outline, text, role, capability, limit = 12) {
+    const query = text?.trim();
+    const roleQuery = role ? normalizedSearchRole(role) : undefined;
+    const actionQuery = capability?.trim();
+    const strong = [];
+    const fuzzy = [];
+    for (const [order, node] of outline.nodes.entries()) {
+        if (roleQuery && normalizedSearchRole(node.role) !== roleQuery)
+            continue;
+        if (actionQuery && !actionMatches(node, actionQuery))
+            continue;
+        const label = outlineNodeLabel(node);
+        const match = query
+            ? rankedTextMatch([
+                label,
+                node.identifier,
+                node.title,
+                node.description,
+                node.value,
+                ...node.text.map((item) => item.string),
+            ], query)
+            : undefined;
+        if (query && !match)
+            continue;
+        const result = {
+            ref: node.ref,
+            role: node.role,
+            label,
+            actions: node.actions,
+            path: outlineNodePath(node),
+            matchReason: match?.reason ?? "filter",
+            score: match?.score ?? 1,
+            node,
+            order,
+        };
+        (match?.reason === "fuzzy" ? fuzzy : strong).push(result);
+    }
+    const rank = { exact: 0, prefix: 1, substring: 2, filter: 3, fuzzy: 4 };
+    const sorted = [
+        ...strong.sort((a, b) => rank[a.matchReason] - rank[b.matchReason] || b.score - a.score || a.order - b.order),
+    ];
+    const useFuzzy = sorted.length < limit;
+    if (useFuzzy)
+        sorted.push(...fuzzy.sort((a, b) => b.score - a.score || a.order - b.order));
+    return {
+        matches: sorted.slice(0, limit).map(({ order: _order, ...match }) => match),
+        totalMatches: strong.length + (useFuzzy ? fuzzy.length : 0),
+    };
+}
+export function searchOutline(outline, text, role, action, limit = 50) {
+    const query = text?.trim().toLowerCase();
+    const roleQuery = role?.trim();
+    const actionQuery = action?.trim();
+    const matches = [];
+    for (const node of outline.nodes) {
+        const label = outlineNodeLabel(node);
+        // outlineNodeLabel short-circuits (title || description || value), so
+        // list the fields individually too or a titled node's value/description
+        // can never match.
+        const haystack = [
+            label,
+            node.role,
+            node.subrole,
+            node.identifier,
+            node.title,
+            node.description,
+            node.value,
+            ...node.text.map((item) => item.string),
+        ]
+            .join(" ")
+            .toLowerCase();
+        if (query && !haystack.includes(query))
+            continue;
+        if (roleQuery && node.role !== roleQuery)
+            continue;
+        if (actionQuery && !actionMatches(node, actionQuery))
+            continue;
+        matches.push({ ref: node.ref, role: node.role, label, actions: node.actions, path: outlineNodePath(node), node });
+        if (matches.length >= limit)
+            break;
+    }
+    return matches;
+}
+export function serializeOutlineSearchMatch(match) {
+    const { node: _node, ...serialized } = match;
+    return serialized;
+}
+export function countOutlineNodes(root) {
+    let count = 1;
+    for (const child of root.children)
+        count += countOutlineNodes(child);
+    return count;
+}
+export function serializeOutline(outline) {
+    return { lookId: outline.lookId, root: serializeOutlineNode(outline.root) };
+}
+export function serializeOutlineNode(node) {
+    const { parent: _parent, children, ...rest } = node;
+    return { ...rest, children: children.map(serializeOutlineNode) };
+}
+export function serializeOutlineNodeShallow(node) {
+    const { parent: _parent, children: _children, ...rest } = node;
+    return { ...rest, children: [] };
+}
+export function restoreOutline(serialized) {
+    const nodes = [];
+    const refToWireRef = new Map();
+    const wireRefToRef = new Map();
+    const restoreNode = (raw, parent) => {
+        const node = { ...raw, children: [], parent };
+        nodes.push(node);
+        if (node.wireRef) {
+            refToWireRef.set(node.ref, node.wireRef);
+            wireRefToRef.set(node.wireRef, node.ref);
+        }
+        node.children = raw.children.map((child) => restoreNode(child, node));
+        return node;
+    };
+    const root = restoreNode(serialized.root);
+    return { lookId: serialized.lookId, root, nodes, refToWireRef, wireRefToRef };
+}
+function outlineRefNumber(ref) {
+    const match = /^@e(\d+)$/.exec(ref);
+    return match ? Number(match[1]) : 0;
+}
+function clearScopedRects(node) {
+    // Scoped look geometry is in the scoped image's pixel space, not the full look.
+    // Until helper-side act carries stable look geometry, grafted nodes are AX-only
+    // for ref actions; coordinate fallback must re-observe the full window.
+    node.rect = undefined;
+    for (const text of node.text)
+        text.rect = undefined;
+    for (const child of node.children)
+        clearScopedRects(child);
+}
+function rebuildIndexes(outline) {
+    outline.nodes = [];
+    outline.refToWireRef = new Map();
+    outline.wireRefToRef = new Map();
+    const queue = [outline.root];
+    let index = 0;
+    while (index < queue.length) {
+        const node = queue[index++];
+        outline.nodes.push(node);
+        if (node.wireRef) {
+            outline.refToWireRef.set(node.ref, node.wireRef);
+            outline.wireRefToRef.set(node.wireRef, node.ref);
+        }
+        queue.push(...node.children);
+    }
+}
+function copyNodeFields(target, source, preserveWireRef = false) {
+    if (!preserveWireRef)
+        target.wireRef = source.wireRef;
+    target.role = source.role;
+    target.subrole = source.subrole;
+    target.identifier = source.identifier;
+    target.title = source.title;
+    target.description = source.description;
+    target.value = source.value;
+    target.actions = [...source.actions];
+    target.canPress = source.canPress;
+    target.canFocus = source.canFocus;
+    target.canSetValue = source.canSetValue;
+    target.canScroll = source.canScroll;
+    target.canIncrement = source.canIncrement;
+    target.canDecrement = source.canDecrement;
+    target.isTextInput = source.isTextInput;
+    target.rect = source.rect;
+    target.focused = source.focused;
+    target.offscreen = source.offscreen;
+    target.pictureOnly = source.pictureOnly;
+    target.truncated = false;
+    target.scrollExtent = source.scrollExtent ? { ...source.scrollExtent } : undefined;
+    target.text = source.text.map((text) => ({ ...text, rect: text.rect ? { ...text.rect } : undefined }));
+}
+function preserveUnreused(node, parent, used) {
+    if (used.has(node))
+        return undefined;
+    node.parent = parent;
+    node.children = node.children
+        .map((child) => preserveUnreused(child, node, used))
+        .filter((child) => Boolean(child));
+    return node;
+}
+function cloneForGraft(source, parent, nextRef, reusableByWireRef, used) {
+    const existing = source.wireRef ? reusableByWireRef.get(source.wireRef) : undefined;
+    if (existing)
+        used.add(existing);
+    const oldChildren = existing?.children ?? [];
+    const node = existing ?? {
+        ...source,
+        ref: nextRef(),
+        children: [],
+        parent,
+        text: [],
+        actions: [],
+        scrollExtent: undefined,
+    };
+    copyNodeFields(node, source, Boolean(existing));
+    node.parent = parent;
+    const graftedChildren = source.children.map((child) => cloneForGraft(child, node, nextRef, reusableByWireRef, used));
+    const preservedChildren = oldChildren
+        .map((child) => preserveUnreused(child, node, used))
+        .filter((child) => Boolean(child));
+    node.children = [...graftedChildren, ...preservedChildren];
+    return node;
+}
+export function graftScopedOutline(outline, targetRef, scoped) {
+    const target = nodeByRef(outline, targetRef);
+    if (!target)
+        throw new Error(`Cannot graft scoped outline: target ${targetRef} is not in the current outline.`);
+    const targetRect = target.rect ? { ...target.rect } : undefined;
+    const reusableByWireRef = new Map();
+    const collect = (node) => {
+        if (node.wireRef)
+            reusableByWireRef.set(node.wireRef, node);
+        for (const child of node.children)
+            collect(child);
+    };
+    collect(target);
+    let nextNumber = Math.max(...outline.nodes.map((node) => outlineRefNumber(node.ref)), 0) + 1;
+    const nextRef = () => `@e${nextNumber++}`;
+    const oldChildren = target.children;
+    const used = new Set([target]);
+    copyNodeFields(target, scoped.root, true);
+    target.ref = targetRef;
+    target.rect = targetRect;
+    const graftedChildren = scoped.root.children.map((child) => cloneForGraft(child, target, nextRef, reusableByWireRef, used));
+    const preservedChildren = oldChildren
+        .map((child) => preserveUnreused(child, target, used))
+        .filter((child) => Boolean(child));
+    target.children = [...graftedChildren, ...preservedChildren];
+    for (const child of target.children)
+        clearScopedRects(child);
+    rebuildIndexes(outline);
+    return target;
+}
+//# sourceMappingURL=outline.js.map