Add AI-callable McMaster-Carr search and part insertion

[10-X-eng]

Problem

The McMaster-Carr integration is currently human-only. A user can open the catalog, search, download 3-D CAD, and let VibeCAD import it, but the AI cannot perform the equivalent workflow. Even when the user's request identifies the needed hardware, a human must leave the conversation, drive the catalog UI, choose a part, and initiate the download.

This prevents workflows such as:

Find a zinc-plated 1/4-20 low-profile socket-head screw, 1.5 inches long, show me the matching McMaster choices, and insert the one I select.

The existing implementation already provides useful local infrastructure: persistent authenticated browser profiles, per-session download inboxes, CAD caching, part-number metadata, and import into PartDesign::Component. The missing layer is a safe, structured, AI-callable catalog workflow.

User-visible outcome

VibeCAD's AI can search McMaster-Carr, return a bounded set of relevant candidates, resolve an exact catalog part, retrieve its supported 3-D CAD, and insert it into the active document without requiring the user to manually operate the catalog.

The human Catalog and Import commands must remain available and behaviorally unchanged.

Proposed capability surface

Add an additive McMaster tool surface with separate read and mutation operations. Exact names can follow the repository's Native capability conventions, but the responsibilities should remain distinct:

• Search: accept free text and structured filters; return a bounded candidate list containing part number, catalog description, relevant dimensions/specifications, CAD availability, and the canonical product URL.
• Inspect: resolve one exact part number and return its normalized specifications and available CAD formats.
• Insert: download or reuse cached CAD for one exact part number, validate the artifact, import it through the existing McMaster import path, and return the created document-object identities.
• Status/cancel: expose progress for browser navigation, authentication, download, validation, and import without blocking the GUI thread.

Search must not silently choose among materially different candidates. When the request is ambiguous, the AI should present the narrowed choices and ask the user which exact part to insert.

Authentication and security

• Reuse the existing local McMaster browser profile so a user's authenticated session survives restarts and upgrades.
• Never expose cookies, credentials, browser storage, or authentication tokens to the model or provider transcript.
• If interactive login, MFA, consent, or a challenge is required, pause with an actionable status and allow the user to complete it in the existing catalog window before resuming.
• Do not invent or depend on a private/unsupported McMaster API. Use a documented supported interface when one is available; otherwise use the existing browser-mediated session and document its compatibility/failure behavior.
• Do not add ordering, purchasing, cart mutation, or account-management capabilities as part of this issue.

Correctness and lifecycle requirements

• Run catalog navigation, search extraction, and downloads off the GUI thread with visible status-bar progress and cancellation.
• Keep returned search data bounded and schema-validated so large catalog pages cannot overflow the Native state or provider context.
• Bind every insert to one exact part number and one validated downloaded artifact.
• Reuse the existing cache when the exact part and artifact are already present; do not create duplicate downloads or duplicate document objects after a retry unless the user explicitly requests another instance.
• Preserve McMaster part number, description, source URL, and artifact identity on the imported component.
• Use a per-operation inbox and clean temporary files after success, cancellation, or failure while retaining valid cached CAD.
• Surface authentication failures, unavailable CAD formats, download failures, validation failures, and import failures separately.
• Keep behavior additive and compatible across Windows, macOS, and Linux backends. A backend that cannot support autonomous search must report that capability clearly and retain the human workflow.

Acceptance criteria

• The AI can search by natural-language description, exact part number, and supported structured filters.
• Search returns a bounded, deterministic, schema-validated candidate list with enough specifications for the user or AI to distinguish choices.
• The AI can inspect an exact candidate before downloading it.
• The AI can download and insert an exact selected part into the active document using the existing component/import conventions.
• Ambiguous searches require explicit narrowing rather than silently inserting an arbitrary result.
• Existing authenticated browser state is reused locally without credentials entering model context or logs.
• Login/challenge-required states can transition to human completion and then resume the pending operation.
• Search/download/import work is asynchronous, cancellable, and reports meaningful status without freezing the VibeCAD UI.
• Retries are idempotent for downloads and do not accidentally duplicate imported objects.
• Temporary inbox data is cleaned up and valid cached CAD remains reusable.
• The existing human Catalog, Import, cache, and placement workflows continue to work unchanged.
• Red/green tests cover schemas, bounded results, ambiguity, credential isolation, caching, retries, cancellation, failure reporting, and exact imported-object receipts.
• Platform integration coverage verifies the supported Windows, macOS, and Linux browser backends or their explicit capability fallback.

Non-goals

• Purchasing, ordering, cart changes, account changes, or price/availability guarantees.
• Sending McMaster credentials or browser-session data to an AI provider.
• Replacing or removing the existing human-operated McMaster catalog experience.

[10-X-eng]

Proposed implementation architecture

Implement this by extending the authenticated browser integration already shipped with VibeCAD, rather than adding a second browser stack or exposing credentials to the model.

1. First-class Native surface and tools

Add an additive mcmaster Native ribbon surface and two bounded capabilities:

• mcmaster.catalog: search, inspect_part, and cad_formats
• mcmaster.insert: insert_part

Search and inspection are read-only. Insertion requires one exact part number and a current Native document ticket. Ambiguous searches return candidates and require narrowing; they must never silently insert an arbitrary match.

2. Local authenticated browser broker

Extend the existing WebView2, WKWebView, and WebKitGTK helpers with a small versioned local JSON request/response protocol. The broker should:

• reuse the existing persistent browser profile and authenticated McMaster session;
• navigate and execute a tightly controlled page-extraction script;
• verify the active origin is McMaster before accepting any result;
• return only bounded normalized part data, never raw page HTML, cookies, tokens, or browser storage;
• expose explicit ready, login_required, challenge_required, unsupported_layout, and failure states;
• make the catalog visible when the user must complete login, MFA, consent, or a challenge, then resume the pending operation;
• use semantic page invariants and part-number patterns rather than generated CSS classes;
• fail closed with CATALOG_LAYOUT_UNSUPPORTED if McMaster changes the page contract.

3. Existing background-job infrastructure

Run navigation, extraction, and downloads through NativeBackgroundManager and expose progress/cancellation through native.job. Suggested stages:

1. Opening catalog
2. Waiting for authentication
3. Searching catalog
4. Inspecting exact part
5. Downloading STEP
6. Validating artifact
7. Importing component

Only the final FreeCAD document mutation should run on the document/GUI thread.

4. Strict Native import path

Keep the current forgiving human import_cad() behavior unchanged. Add a strict compatible wrapper, such as import_cad_exact(), for AI mutations that:

• imports through the existing McMaster STEP/component implementation;
• runs in one transaction;
• requires one verified PartDesign::Component result;
• stamps the exact part number, description, canonical source URL, CAD format, artifact hash, and insertion operation ID;
• does not rely on delayed Qt relabel callbacks for correctness;
• rolls back the entire import on any failure;
• returns exact Native object references and a bounded mutation receipt.

5. Cache and retry identity

Track two independent identities:

• Artifact identity: exact part number + CAD format + downloaded-content hash. This controls download reuse.
• Insertion identity: one stable operation/request ID. Retrying the same insertion returns its existing receipt instead of creating a duplicate object.

An intentional request for another physical instance receives a new insertion ID while reusing the cached CAD artifact.

6. Optional official API provider

Define a provider interface with:

• BrowserCatalogProvider as the default zero-configuration path;
• McMasterApiProvider as an optional enterprise path for approved customers.

McMaster's documented Product Information API supports exact product information and CAD retrieval but requires an approved account, client certificate, authenticated token, subscriptions, and rate limits. Its documented endpoint table does not expose general natural-language catalog search, so the API cannot replace browser search for ordinary users. API credentials must use OS credential storage and must never enter preferences, logs, or model context.

7. Required tests

• Red/green unit tests for every schema, bound, origin check, authentication state, ambiguity rule, and failure code.
• Sanitized captured-page fixtures for search and exact-part normalization.
• Local fake-catalog integration page for deterministic browser RPC and download tests; ordinary CI must not depend on the live McMaster site.
• Retry/idempotency tests proving the same operation cannot duplicate document objects.
• Transaction tests proving strict import completely rolls back partial failures.
• Credential-isolation tests proving cookies, tokens, passwords, and raw browser data cannot enter provider results or diagnostics.
• Packaged WebView2, WKWebView, and WebKitGTK smoke tests, plus a manual live McMaster acceptance gate before release.

This should remain one coherent feature PR, developed internally in the order: broker contract, Windows adapter, Native tools/background flow, strict import, then macOS/Linux adapters and packaged acceptance.