@algolia/wizard 0.69.0 → 0.71.0

package/dist/main.js

@@ -1969,7 +1969,7 @@ function identify(traits) {
 // package.json
 var package_default = {
   name: "@algolia/wizard",
-  version: "0.69.0",
+  version: "0.71.0",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {
@@ -3440,6 +3440,12 @@ var DEFAULT_TOOL_LIMITS = {
   match: 100,
   shell: 50
 };
+var EMPTY_TOOL_COUNTS = {
+  list: 0,
+  search: 0,
+  read: 0,
+  shell: 0
+};
 var DEFAULT_SHELL_TIMEOUT_MS = 10 * 60 * 1e3;
 async function refuseByDefault() {
   return "reject";
@@ -3458,11 +3464,14 @@ function createToolContext(limits = DEFAULT_TOOL_LIMITS, cwd = process.cwd(), sh
     root: cwd,
     cwd,
     limits: { ...limits },
-    counts: { list: 0, search: 0, read: 0, shell: 0 },
+    counts: { ...EMPTY_TOOL_COUNTS },
     shell: shell2,
     reviewed: []
   };
 }
+function resetToolCounts(ctx) {
+  Object.assign(ctx.counts, EMPTY_TOOL_COUNTS);
+}
 
 // src/lib/tools/utils/runShell.ts
 var SIGKILL_DELAY_MS = 5e3;
@@ -4128,10 +4137,21 @@ var MISSING_REPORT_STATUS_ERROR_MESSAGE = "Agent finished without calling report
 var MISSING_REPORT_USER_MESSAGE = "This step ran into a problem finishing. Run the wizard again to retry it.";
 var REPORT_STATUS_RETRIES = 2;
 var ATTEMPT_NUMBER_OFFSET = 1;
+var INITIAL_ATTEMPT = 0;
 var PROVIDER_ERROR_USER_MESSAGE = "The AI service had trouble responding. Run the wizard again to retry this step.";
+var MissingReportError = class extends Error {
+  atStepLimit;
+  constructor(atStepLimit) {
+    super(MISSING_REPORT_STATUS_ERROR_MESSAGE);
+    this.atStepLimit = atStepLimit;
+  }
+};
+function isMissingReportRetry(kind) {
+  return kind === "missingReport" || kind === "missingReportAtStepLimit";
+}
 function retryKind(err) {
-  if (err instanceof Error && err.message === MISSING_REPORT_STATUS_ERROR_MESSAGE) {
-    return "missingReport";
+  if (err instanceof MissingReportError) {
+    return err.atStepLimit ? "missingReportAtStepLimit" : "missingReport";
   }
   if (NoOutputGeneratedError.isInstance(err)) return "transientProvider";
   if (APICallError.isInstance(err) && err.isRetryable) {
@@ -4140,37 +4160,42 @@ function retryKind(err) {
   return null;
 }
 function exhaustedError(kind, err) {
-  return kind === "missingReport" ? new Error(MISSING_REPORT_USER_MESSAGE) : new Error(PROVIDER_ERROR_USER_MESSAGE, { cause: err });
+  return isMissingReportRetry(kind) ? new Error(MISSING_REPORT_USER_MESSAGE) : new Error(PROVIDER_ERROR_USER_MESSAGE, { cause: err });
 }
 async function runAgent(req) {
-  for (let attempt = 0; attempt <= REPORT_STATUS_RETRIES; attempt++) {
+  let retryReason = null;
+  for (let attempt = INITIAL_ATTEMPT; attempt <= REPORT_STATUS_RETRIES; attempt++) {
     try {
-      return await runAgentAttempt(req, attempt);
+      return await runAgentAttempt(req, attempt, retryReason);
     } catch (err) {
       const kind = retryKind(err);
       if (!kind) throw err;
       if (attempt === REPORT_STATUS_RETRIES) throw exhaustedError(kind, err);
+      retryReason = kind === "transientProvider" && isMissingReportRetry(retryReason) ? retryReason : kind;
       logger.warn(
         { attempt: attempt + 1, err },
-        kind === "missingReport" ? "retrying runAgent after missing reportStatus" : "retrying runAgent after a transient provider error"
+        isMissingReportRetry(kind) ? "retrying runAgent after missing reportStatus" : "retrying runAgent after a transient provider error"
       );
     }
   }
   throw new Error("unreachable");
 }
-async function runAgentAttempt(req, attempt) {
+async function runAgentAttempt(req, attempt, retryReason) {
   const start = Date.now();
   const profileName = req.modelProfile ?? "implementation" /* implementation */;
   const profile = getModelProfile(profileName);
-  const modelOptions = providerOptionsForProfile(profileName);
+  const profileOptions = providerOptionsForProfile(profileName);
+  const forceReport = retryReason === "missingReport";
+  const modelOptions = forceReport ? { thinking: { type: "disabled" } } : profileOptions;
   logger.info(
     {
       startedAt: new Date(start).toISOString(),
       operation: req.operation,
       profile: profileName,
       model: profile.model,
-      effort: profile.effort,
-      thinking: profile.thinking
+      effort: forceReport ? void 0 : profile.effort,
+      thinking: forceReport ? "disabled" : profile.thinking,
+      retryReason
     },
     "runAgent started"
   );
@@ -4184,6 +4209,7 @@ async function runAgentAttempt(req, attempt) {
     fetch: proxyFetch
   });
   const toolContext = req.toolContext ?? createToolContext();
+  if (attempt > INITIAL_ATTEMPT) resetToolCounts(toolContext);
   const readTools = ["readFile", "searchFiles", "listFiles"];
   const hasReadTools = !req.tools || req.tools.some((t) => readTools.includes(t));
   const instructions = [
@@ -4195,8 +4221,14 @@ async function runAgentAttempt(req, attempt) {
     // Last so a retry does not bust the cached tools+system prefix from
     // the first attempt. Inspect-and-continue, not start over: implement
     // shares the worktree and toolContext across attempts.
-    ...attempt > 0 ? [
-      "This run is a retry after a previous attempt that did not finish. Files, shell commands, or ingestion may already have been applied in this workspace \u2014 inspect what is already there and continue from it rather than repeating that work."
+    ...retryReason === "missingReport" ? hasReadTools ? [
+      "The previous attempt ended without reportStatus. Do not repeat side effects. Use the available read tools to inspect existing work if needed, then call reportStatus."
+    ] : [
+      "The previous attempt ended without reportStatus. Do not repeat side effects. Call reportStatus now."
+    ] : retryReason === "missingReportAtStepLimit" ? [
+      "The previous attempt reached its step limit without reportStatus and may be incomplete. Inspect existing work, finish only the remaining work, avoid repeated side effects, and call reportStatus."
+    ] : attempt > 0 ? [
+      "This run is a retry after a transient AI service error. Files, shell commands, or ingestion may already have been applied in this workspace \u2014 inspect what is already there and continue from it rather than repeating that work."
     ] : []
   ];
   const agent = new ToolLoopAgent({
@@ -4304,7 +4336,8 @@ async function runAgentAttempt(req, attempt) {
       },
       "Agent finished without calling reportStatus"
     );
-    throw new Error(MISSING_REPORT_STATUS_ERROR_MESSAGE);
+    const incomplete = steps.length >= profile.maxSteps || lastStep?.finishReason !== "stop";
+    throw new MissingReportError(incomplete);
   }
   const result = report.output;
   if (result.status !== "success") {
@@ -4426,10 +4459,14 @@ var MODE_CONFIG = {
   },
   searchImplementation: {
     instructions: [
-      "Analyze the codebase to determine the single best location to add search UI functionality.",
-      "Prefer a shared, always-rendered layout location (e.g. a header or navigation component) so search is reachable across the app.",
+      "Analyze the codebase to determine the single best existing file in which to mount search UI.",
+      "Inspect the layout hierarchy, routes, and the candidate file together with its parent and sibling components; do not choose a location from its filename alone.",
+      "Identify the pages and components that display or browse the indexed domain content, plus any existing search, filter, or navigation controls. Details of the confirmed entity are appended below when the wizard already knows them; otherwise infer the likely indexed domain content from the codebase.",
+      "Match placement to search scope: put content-specific search near the corresponding browse/list controls; use a shared header or navigation component only when search is genuinely app-wide and fits its visual hierarchy.",
+      "Account for available space, alignment, and behavior at the app's existing responsive breakpoints so the control will not crowd or displace primary navigation.",
+      "Prefer an existing search control with the same content scope when one can be replaced without removing unrelated filters or navigation.",
       "Return one file path as searchImplementationAnalysis (e.g. /layouts/header.tsx).",
-      'Use as few tools as possible, but do not guess. If you cannot find a clear location, say "unknown".',
+      'Spend your reads on the layout entry point, the candidate file with its parent and siblings, and the UI that lists the indexed content \u2014 around a dozen targeted reads or searches, not a repo-wide crawl. Stop once one location is clearly best, and do not guess: if none is, say "unknown".',
       "Ignore directories that may be related to testing, like `/fixtures`, `/tests`, etc",
       "When done, call reportStatus"
     ],
@@ -4684,7 +4721,8 @@ import z26 from "zod";
 var confirmEntitiesSchema = z26.object({
   // Final detection — the focused re-run may supersede project-scan's.
   ingestionAnalysis: ingestionAnalysisSchema.shape.ingestionAnalysis.optional(),
-  confirmedEntities: confirmedEntitiesFieldSchema
+  confirmedEntities: confirmedEntitiesFieldSchema,
+  searchImplementationAnalysis: searchImplementationAnalysisSchema.shape.searchImplementationAnalysis.optional()
 });
 var SUGGEST_ENTITY = "Suggest a different entity\u2026";
 function usedDetectedBackend(detected, confirmed2) {
@@ -4807,7 +4845,26 @@ async function confirmEntities(ctx) {
       attribute_count: summary[0]?.attributes.length ?? 0,
       used_detected_back_end: usedDetectedBackend(scan.languages, languages)
     });
-    return { ingestionAnalysis: entities, confirmedEntities: confirmed2 };
+    let searchImplementationAnalysis = scan.searchImplementationAnalysis;
+    try {
+      const placement = await runAnalysis("searchImplementation", [
+        `The user confirmed this indexed entity: ${JSON.stringify(confirmed2[0])}. Determine placement specifically for this content and its existing user task; do not substitute another domain found in the repository.`
+      ]);
+      searchImplementationAnalysis = placement.searchImplementationAnalysis;
+    } catch (err) {
+      logger.warn({ err }, "confirmEntities: placement refresh failed");
+    }
+    if (searchImplementationAnalysis) {
+      ctx.setUserInput(
+        "searchImplementationAnalysis",
+        searchImplementationAnalysis
+      );
+    }
+    return {
+      ingestionAnalysis: entities,
+      confirmedEntities: confirmed2,
+      searchImplementationAnalysis
+    };
   }
 }
 
@@ -5133,19 +5190,37 @@ function ingestionInstructions(input) {
   ];
 }
 function searchInstructions(input) {
-  const entity = input.findings.confirmedEntities ? input.findings.confirmedEntities[0].name : null;
-  const attributes = input.findings.confirmedEntities ? input.findings.confirmedEntities[0].attributes : null;
-  const entitySchemaMessage = entity && attributes ? `The following entity schema should be used to build the UI: ${JSON.stringify({ entity, attributes })}` : null;
+  const indexedEntity = input.findings.confirmedEntities?.[0];
+  const indexedContentMessage = indexedEntity ? `Indexed content context: ${JSON.stringify({
+    entity: indexedEntity.name,
+    attributes: indexedEntity.attributes,
+    sourcePaths: indexedEntity.paths
+  })}. Use the source and the existing UI that displays this entity to understand the search task, result content, and appropriate scope.` : null;
+  const mountCandidateMessage = input.searchLocation ? `The confirmed-content placement analysis suggested "${input.searchLocation}" as a mount candidate. Before editing, read that file and inspect its parent layout, sibling controls, and the relevant content UI. If the evidence confirms it, import and render the new search component there; otherwise mount it in the better existing file. In all cases, mount the component before finishing; do not leave an unrendered component.` : "The scan found no reliable mount candidate. Determine the best existing location from the layout hierarchy and the UI that displays the indexed content, then mount the new search component there; do not default to a header or navigation component or leave an unrendered component.";
+  const placementMessage = "Place content-specific search beside the heading or controls for the corresponding browse/listing task. Use shared navigation only for genuinely app-wide search and only when it fits the available space and responsive layout without crowding primary actions.";
+  const replacementMessage = "If a search control with the same content scope and purpose already exists, replace its usage with the new component while preserving its intentional placement, and delete the implementation it supersedes. Do not remove or replace unrelated filters, navigation, or differently scoped search.";
+  const accessibilityInstructions = [
+    "Target WCAG 2.2 AA. Use semantic search structure and give the input a persistent accessible name: prefer a visible associated label and use the project's visually-hidden utility where the layout has no room for one. A placeholder or a labeled search landmark does not name the input. When the input uses aria-labelledby, every referenced element must exist and contain meaningful, content-specific text. Preserve a widget's generated label when it provides one and make it content-specific through supported options; if the installed widget exposes no such option, use its documented connector or headless API to render a labeled input instead of patching generated DOM.",
+    "Preserve widget-provided combobox, popup, and item roles, relationships, and keyboard behavior; for a headless widget, implement the documented semantics instead of inventing different ARIA. Tab must reach the input and controls, Arrow keys move through results, Enter selects, and Escape dismisses without trapping or losing focus.",
+    "Meet 4.5:1 contrast for normal text, including input values, placeholders, and result text, and 3:1 for large text, meaningful icons, control boundaries, and focus indicators against adjacent colors. Keep focus visible and unobscured, and never communicate active, loading, empty, or error states by color alone.",
+    "Keep loading, empty, and error status text perceivable to assistive technology. Do not assume a widget announces these states: use documented announcements when present, otherwise add a persistent polite live region driven by the current search status, results, and errors.",
+    "Reflow at a 320 CSS-pixel viewport without horizontal page scrolling, keep the results panel readable and on-screen whatever the width of the input it hangs off, keep interactive targets at least 24 by 24 CSS pixels or sufficiently spaced, and respect prefers-reduced-motion for any animation you add."
+  ];
   const packageManagedInstructions = input.frontendHasPackageJson ? packageSearchInstructions(input) : cdnSearchInstructions(input);
   return [
     "Implement an in-app Algolia search experience.",
-    entitySchemaMessage ?? "",
+    indexedContentMessage ?? "",
     `Build the search UI for ${input.searchUiTarget}.`,
     "Create search UI only. Do not create or modify ingestion scripts, rake/manage/CLI tasks, migrations, seeders, or other data-loading code, even if the data looks incomplete.",
+    mountCandidateMessage,
+    placementMessage,
+    replacementMessage,
+    "Inspect the chosen mount area at the app's existing breakpoints before writing CSS. Preserve its visual hierarchy, alignment, spacing, and primary actions rather than forcing the search control into an arbitrary gap.",
     ...packageManagedInstructions,
-    "Meet WCAG AA contrast (4.5:1 body text, 3:1 large text/icons) between the panel's text and its own background, and give the input and the active result a focus indicator visible against whatever sits behind it. Style the panel through the widget's class and CSS-variable overrides (or, when hand-built, the app's existing theme tokens) \u2014 never assume a light surface or reuse the surrounding page's colors unchanged inside the panel.",
-    "The panel takes its width from the input by default, so a small input makes it unreadably narrow: give it a min-width of 320px independent of the input, anchored to the input edge it opens from so widening does not push it off-screen.",
-    "Match the styles of the application as closely as possible.",
+    ...accessibilityInstructions,
+    "Style the search surfaces through the widget's class and CSS-variable overrides (or, when hand-built, the app's existing theme tokens): give the results panel and the element that actually draws the input's border and background \u2014 for a widget, the form or wrapper it renders around the bare input \u2014 non-transparent surfaces, keep that frame distinguishable from the background behind it in every supported theme, and never assume a light surface or reuse the surrounding page's colors unchanged inside the panel.",
+    "The panel takes its width from the input by default, so a small input makes it unreadably narrow: give it `min-width: min(320px, calc(100vw - 2rem))` independent of the input, cap its maximum width to the viewport, and anchor it to the input edge it opens from so widening does not push it off-screen.",
+    "Match the application styles closely, including light, dark, and high-contrast themes the project already supports.",
     "The summary should be extremely concise; do not mention manual testing steps."
   ];
 }
@@ -5159,8 +5234,6 @@ function packageSearchInstructions(input) {
       "No bundled Algolia SDK reference exists for this stack, so rely on the project's own conventions and Algolia's official client for its language. Do not invent APIs \u2014 keep to the documented search endpoint and its parameters."
     ],
     `Create the search experience as its own component in a new file, following the project's existing component conventions (location, naming, styling approach). Do not write it inline into an existing file.`,
-    `Import and render the new component in ${input.searchLocation ? `"${input.searchLocation}"` : "the best, always-rendered layout location (e.g. a header/nav component)"} so it is reachable across the app \u2014 at least a working search input and results panel against the target index.`,
-    "If a search box already exists, replace its usage with an import and render of your new component; remove the old implementation.",
     "When rendering results with an existing shared component (e.g. a card), import and reuse that component rather than inlining its markup \u2014 inlining silently drops the styles and behavior its own file provides.",
     "Vendor theme CSS, and any CSS you write against vendor class names, must be global: import the theme from the component's own script module or the app's global stylesheet, and put overrides in a global block (Astro <style is:global>, an unscoped Vue block, a plain global CSS file). Never a framework-scoped style block or a CSS Module \u2014 scoping rewrites the vendor selectors and the widget's runtime DOM carries no scope attribute, so not one rule matches: styling silently does nothing and the build still passes.",
     `Define ${SEARCH_CONFIG_APP_ID}, ${SEARCH_CONFIG_SEARCH_KEY}, and ${SEARCH_CONFIG_INDEX_NAME} as exported constants in a module that fits this project's existing conventions for shared client-side config \u2014 reuse an existing one if it already holds config like this, or add a small new one otherwise. These are PUBLIC values, safe to commit and expose client-side: never read them from an environment variable or a .env* file, and never hardcode them anywhere except in that one module (import them wherever the search client needs them).`,
@@ -5171,21 +5244,29 @@ function packageSearchInstructions(input) {
   ];
 }
 function cdnSearchInstructions(input) {
+  const entityName = input.findings.confirmedEntities?.[0]?.name;
+  const placeholder = entityName ? `Search ${entityName} records...` : "Search indexed content...";
   return [
     `The target frontend has no package.json. Add the search container to its existing HTML or template, create separate classic config and search scripts, define window.${SEARCH_CONFIG_APP_ID}, window.${SEARCH_CONFIG_SEARCH_KEY}, and window.${SEARCH_CONFIG_INDEX_NAME} in the config script, and report that script as "searchConfigFile". Never create package.json, create a component, use imports or exports, or run npm, pnpm, yarn, or bun.`,
     `Set window.${SEARCH_CONFIG_APP_ID} to "${input.appId}" and window.${SEARCH_CONFIG_INDEX_NAME} to "${input.targetIndex}".`,
     input.searchKey ? `Set window.${SEARCH_CONFIG_SEARCH_KEY} to "${input.searchKey}".` : `A real search-only key could not be provisioned${input.searchKeyError ? ` (${input.searchKeyError})` : ""} \u2014 set window.${SEARCH_CONFIG_SEARCH_KEY} to the placeholder "${SEARCH_KEY_PLACEHOLDER}" and add a prominent TODO for the developer to fill in a real one.`,
     'Load these exact pinned tags in order before the config and search scripts: <script src="https://cdn.jsdelivr.net/npm/algoliasearch@5.59.0/dist/lite/builds/browser.umd.js" integrity="sha256-pduQHl1jn0IaN/BIpSotQm7Y5THdpKcX3Bw6xdRteRw=" crossorigin="anonymous"></script> then <script src="https://cdn.jsdelivr.net/npm/instantsearch.js@4.117.0/dist/instantsearch.production.min.js" integrity="sha256-5zhKxAGeH7ThWfnmdD4pS1gsmafE2b8aWRsq8set/dc=" crossorigin="anonymous"></script>.',
     'When using the InstantSearch theme, load this exact tag before the application styles: <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@8.22.1/themes/satellite-min.css" integrity="sha256-5/eHPZl63VYJSDVOKrOgGe/5+owUkX3uPAW6+XYeLNc=" crossorigin="anonymous">. Never use an unversioned or differently versioned theme URL, and never omit its integrity attribute.',
-    `In that classic search script, use window['algoliasearch/lite'].liteClient and window.instantsearch. Add window.instantsearch.widgets.autocomplete as the only search widget. Configure it with container '#autocomplete', placeholder 'Search...', and an indices array containing one object whose indexName is window.${SEARCH_CONFIG_INDEX_NAME}; put item and noResults functions in its templates option, implement getURL only for an existing route, and match the item template to the entity schema. Keep insights: true and call search.start(). Do not substitute searchBox or hits, omit indices, use imports or exports, or use type="module".`
+    `In that classic search script, use window['algoliasearch/lite'].liteClient and window.instantsearch. Add window.instantsearch.widgets.autocomplete as the only search widget. Configure it with container '#autocomplete', the content-specific placeholder ${JSON.stringify(placeholder)}, and an indices array containing one object whose indexName is window.${SEARCH_CONFIG_INDEX_NAME}; put item and noResults functions in its templates option, implement getURL only for an existing route, and match the item template to the entity schema. Keep insights: true and call search.start(). Do not substitute searchBox or hits, omit indices, use imports or exports, or use type="module".`
   ];
 }
 function validationInstructions(input) {
   return [
     "Validate the Algolia search implementation by inspecting the project source.",
+    `Indexed content context: ${JSON.stringify(input.findings.confirmedEntities?.[0] ?? null)}.`,
+    `The confirmed placement candidate was "${input.searchLocation ?? "unknown"}", but verify the actual mount rather than assuming the candidate was used.`,
+    "Inspect the generated search component, its actual mount file, that file's parent layout and sibling controls, and the relevant content UI. Do not rely only on lint, type checks, or tests.",
     "Confirm that the application renders exactly one search bar. Check for an old search bar and duplicate mounts.",
-    `Confirm that the search bar is mounted in ${input.searchLocation ? `"${input.searchLocation}"` : "the best always-rendered shared layout location"}.`,
-    "Confirm that the search component is reachable across the application and fits the surrounding layout.",
+    "Confirm content-specific search is placed with the corresponding content or task controls. Shared navigation is valid only for genuinely app-wide search that fits the visual hierarchy and responsive layout without crowding primary actions.",
+    "Confirm the input has a persistent accessible name; widget-provided combobox, popup, and item relationships and keyboard behavior are preserved; and loading, empty, and error status text is perceivable to assistive technology.",
+    "Inspect the CSS that actually applies to the generated DOM. Confirm the results panel and the element drawing the input frame have non-transparent surfaces, the input frame is distinguishable from its surrounding background in every supported theme, text meets 4.5:1 contrast, meaningful boundaries and focus indicators meet 3:1, and no state relies on color alone.",
+    "Confirm the search experience reflows without horizontal page scrolling at 320 CSS pixels, keeps its panel on-screen, preserves visible focus, and respects reduced-motion preferences for any added animation.",
+    "Confirm that the search component is reachable from and fits the corresponding content task at every supported breakpoint; require app-wide reachability only when the search scope is genuinely app-wide.",
     "Do not run the test suite or any test command.",
     "Do not modify files. Report each implementation issue as a concrete instruction for the next implementation pass.",
     `Available type-check and lint tools: ${JSON.stringify(input.findings.verification ?? [])}.`,
@@ -5193,8 +5274,10 @@ function validationInstructions(input) {
       "The frontend has no package.json: never create one or run npm, pnpm, yarn, or bun. Validate the CDN implementation by inspecting its HTML or template and classic scripts for the search container, Algolia \u2192 InstantSearch \u2192 config \u2192 search load order, browser globals, autocomplete widget configuration, search.start(), and exact pinned CDN URLs and integrity attributes for every Algolia script or stylesheet. Source inspection is required even when the project has no automated checks. window.instantsearch.widgets.autocomplete is a real widget in the pinned InstantSearch build; do not report its use as an error, and do not fetch a remote bundle or URL to verify it."
     ] : [],
     "Always call reportStatus with status=success after validation, even when sufficient=false.",
-    "Set sufficient=true only when the search bar is unique, correctly placed, and structurally complete.",
-    "Set sufficient=false for an implementation issue. Include concrete additionalInstructions for the next pass.",
+    "Set sufficient=false if the input's computed accessible name is empty or generic, including when aria-labelledby references a missing or empty element; a placeholder does not count as the label.",
+    "Set sufficient=true when the search bar is unique and structurally complete and no placement or accessibility violation was found.",
+    "Set sufficient=false when a required placement or accessibility property is observed to fail, the implementation is incomplete, or checks have implementation-caused failures; include concrete additionalInstructions for the next pass.",
+    "If any required placement or accessibility property cannot be established with the available tools\u2014including contrast, keyboard behavior, 320-pixel reflow, or live-region status\u2014set sufficient=false and request concrete verification or a fix in additionalInstructions; do not let an unverified requirement pass as a manual follow-up.",
     "If a check fails only in untouched code, set unrelatedFailure to a concise failure description."
   ];
 }
@@ -5465,12 +5548,6 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES) {
   const entities = ctx.getStepOutput(
     "confirm-entities"
   );
-  const findings = {
-    ingestionAnalysis: entities?.ingestionAnalysis ?? scan.ingestionAnalysis,
-    searchImplementationAnalysis: scan.searchImplementationAnalysis,
-    verification: scan.verification,
-    confirmedEntities: entities?.confirmedEntities
-  };
   const language = {
     languages: ctx.getStepOutput("confirm-language")?.languages ?? scan.languages,
     frameworks: ctx.getStepOutput("confirm-framework")?.frameworks ?? scan.frameworks
@@ -5495,9 +5572,14 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES) {
   if (useCases.includes("ingestion")) {
     await mkdir5(join10(repoRoot, INGEST_DIR), { recursive: true });
   }
-  const normalized = normalizeFindingPaths(findings);
-  const confirmed2 = normalized.confirmedEntities;
-  const searchLocation = normalized.searchImplementationAnalysis;
+  const findings = normalizeFindingPaths({
+    ingestionAnalysis: entities?.ingestionAnalysis ?? scan.ingestionAnalysis,
+    searchImplementationAnalysis: entities?.searchImplementationAnalysis ?? scan.searchImplementationAnalysis,
+    verification: scan.verification,
+    confirmedEntities: entities?.confirmedEntities
+  });
+  const confirmed2 = findings.confirmedEntities;
+  const searchLocation = findings.searchImplementationAnalysis;
   let appId;
   let ingestAppId;
   if (useCases.includes("search")) {
@@ -5532,7 +5614,7 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES) {
     }
   }
   const input = {
-    findings: normalized,
+    findings,
     confirmed: confirmed2,
     searchLocation,
     targetIndex,
@@ -5560,8 +5642,7 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES) {
     [APP_ID_VAR]: ingestKeyAppId,
     [API_KEY_VAR]: ingestWriteKey,
     [INDEX_NAME_VAR]: targetIndex
-  })) : void 0;
-  const searchTools = makeToolContext(repoRoot);
+  })) : makeToolContext(repoRoot);
   async function runImplementationUseCase(currentUseCase, extraInstructions = [], isRetry = false) {
     if (agentRuns > 0) ctx.recordStepExecution();
     agentRuns += 1;
@@ -5575,23 +5656,29 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES) {
       tools: toolsForUseCase(currentUseCase, input.ingestionSource),
       outputSchema: implementationOutputSchema,
       modelProfile: isRetry ? "implementationRetry" /* implementationRetry */ : "implementation" /* implementation */,
-      toolContext: currentUseCase === "ingestion" ? ingestionTools ?? searchTools : searchTools
+      toolContext: currentUseCase === "ingestion" ? ingestionTools : makeToolContext(repoRoot)
     });
   }
   async function runValidationUseCase(extraInstructions) {
     if (agentRuns > 0) ctx.recordStepExecution();
     agentRuns += 1;
+    const writtenFiles = [...new Set(useWizard.getState().writtenFiles)].map(
+      (file) => relative6(repoRoot, file)
+    );
     return runAgent({
       operation: "search-validation",
       instructions: buildAgentInstructions(
         "validation",
         input,
-        extraInstructions
+        [
+          writtenFiles.length ? `Files written during search implementation: ${JSON.stringify(writtenFiles)}. Inspect these first, then trace the actual import and render site.` : "The search agent reported no written files. Inspect the current diff and set sufficient=false if no complete mounted search implementation exists.",
+          ...extraInstructions
+        ]
       ),
       tools: toolsForUseCase("validation"),
       outputSchema: validationOutputSchema,
       modelProfile: "validation" /* validation */,
-      toolContext: searchTools
+      toolContext: makeToolContext(repoRoot)
     });
   }
   if (useCases.includes("ingestion")) {
@@ -5599,7 +5686,7 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES) {
     const result = await runImplementationUseCase("ingestion");
     summaries.push(formatSummary("ingestion", result.summary));
     ingestCommand = result.ingestCommand;
-    const ingestionContext = ingestionTools ?? searchTools;
+    const ingestionContext = ingestionTools;
     const executions = ingestionContext.shell.executions;
     const {
       run: ingestRun,
@@ -7502,7 +7589,7 @@ function delay(ms) {
 // package.json with { type: 'json' }
 var package_default2 = {
   name: "@algolia/wizard",
-  version: "0.69.0",
+  version: "0.71.0",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {

package/docs/algolia-sdk/instantsearch-setup-js.md

@@ -91,6 +91,40 @@ Ensure the attributes you map into the component match the entity. 'title' above
   `instantsearch.js`), then `autocomplete<ProductHit>({ ... })` types `item`, `getURL`,
   and the templates.
 
+### Accessibility contract
+
+The widget owns its combobox/grid/row relationships, active-option announcements, and
+keyboard behavior. Keep its generated roles and accessible names intact; never patch its
+DOM or add competing ARIA.
+
+The widget renders the input and its label itself. Keep that association intact, and
+verify that the generated label names the indexed content (`Search products`, not just
+`Search`). A placeholder is only a hint, and the accessible name of a surrounding
+`<search>` landmark does not name the input. If the installed widget exposes no supported
+way to make its generated label content-specific, use its documented connector or
+headless API to render an associated visible or visually-hidden label while preserving
+the widget's generated input props and keyboard behavior; never patch its DOM after
+rendering.
+
+Use a content-specific placeholder, put the container in the app's existing named search
+landmark or a `<search aria-label="Product search">`, and preserve any visible search
+label already present in the layout. `translations` covers only the detached-mode
+controls (`detachedCancelButtonText`, `detachedSearchButtonTitle`,
+`detachedClearButtonTitle`) — set them in a non-English app.
+
+The widget does not provide live announcements for loading, empty, or error states. Add
+a persistent `aria-live="polite"` region driven by the current search status, results,
+and errors, hidden with the app's visually-hidden utility if it should not show. Target
+WCAG 2.2 AA and verify after styling that:
+
+- input, placeholder, and result text clear 4.5:1 contrast;
+- meaningful icons, control boundaries, and focus indicators clear 3:1 contrast;
+- focus is visible and unobscured, and no state relies on color alone;
+- all controls remain keyboard-operable and have 24 by 24 CSS pixel targets or enough
+  spacing around smaller targets;
+- the experience reflows at a 320 CSS pixel viewport without horizontal page scrolling;
+- any added animation respects `prefers-reduced-motion`.
+
 ### Styling the panel
 
 The widget ships no CSS. Install `instantsearch.css` and import a theme once, from the
@@ -139,12 +173,15 @@ Everything else is plain CSS against the widget's classes, or `cssClasses` /
 - `.ais-AutocompleteDetached*` — detached mode (below).
 
 The theme's panel is `position: absolute; width: 100%`, so it inherits the input
-container's width — a small input yields an unreadably narrow panel. Give it a min-width
-and anchor it to the edge it opens from, or it grows off-screen:
+container's width — a small input yields an unreadably narrow panel. Give it a 320px
+minimum when space permits, cap it to the viewport, and anchor it to the edge it opens
+from. Give the form and panel non-transparent surfaces from the app's tokens, with the
+form boundary distinguishable from the surrounding background in every supported theme:
 
 ```css
 .ais-AutocompletePanel {
-  min-width: 320px;
+  min-width: min(320px, calc(100vw - 2rem));
+  max-width: calc(100vw - 2rem);
   left: 0; /* right: 0; left: auto for an input aligned to the right */
 }
 ```

package/docs/algolia-sdk/instantsearch-setup-react.md

@@ -83,6 +83,40 @@ Ensure the attributes you map into the component match the entity. 'title' above
   `instantsearch.js`), then `<Autocomplete<ProductHit> ... />` types `item`, `getURL`, and
   `itemComponent`.
 
+### Accessibility contract
+
+The widget owns its combobox/grid/row relationships, active-option announcements, and
+keyboard behavior. Keep its generated roles and accessible names intact; never patch its
+DOM or add competing ARIA.
+
+The widget renders the input and its label itself. Keep that association intact, and
+verify that the generated label names the indexed content (`Search products`, not just
+`Search`). A placeholder is only a hint, and the accessible name of a surrounding
+`<search>` landmark does not name the input. If the installed widget exposes no supported
+way to make its generated label content-specific, use its documented connector or
+headless API to render an associated visible or visually-hidden label while preserving
+the widget's generated input props and keyboard behavior; never patch its DOM after
+rendering.
+
+Use a content-specific placeholder, put the widget in the app's existing named search
+landmark or a `<search aria-label="Product search">`, and preserve any visible search
+label already present in the layout. On `react-instantsearch` 7.24.0+, `translations`
+covers the detached-mode controls (`detachedCancelButtonText`,
+`detachedSearchButtonTitle`, `detachedClearButtonTitle`) — set them in a non-English app.
+
+The widget does not provide live announcements for loading, empty, or error states. Add
+a persistent `aria-live="polite"` region driven by the current search status, results,
+and errors, hidden with the app's visually-hidden utility if it should not show. Target
+WCAG 2.2 AA and verify after styling that:
+
+- input, placeholder, and result text clear 4.5:1 contrast;
+- meaningful icons, control boundaries, and focus indicators clear 3:1 contrast;
+- focus is visible and unobscured, and no state relies on color alone;
+- all controls remain keyboard-operable and have 24 by 24 CSS pixel targets or enough
+  spacing around smaller targets;
+- the experience reflows at a 320 CSS pixel viewport without horizontal page scrolling;
+- any added animation respects `prefers-reduced-motion`.
+
 ### Styling the panel
 
 The widget ships no CSS. Install `instantsearch.css` and import a theme once, from the
@@ -131,12 +165,15 @@ Everything else is plain CSS against the widget's classes, or the `classNames` /
 - `.ais-AutocompleteDetached*` — detached mode (below).
 
 The theme's panel is `position: absolute; width: 100%`, so it inherits the input
-container's width — a small input yields an unreadably narrow panel. Give it a min-width
-and anchor it to the edge it opens from, or it grows off-screen:
+container's width — a small input yields an unreadably narrow panel. Give it a 320px
+minimum when space permits, cap it to the viewport, and anchor it to the edge it opens
+from. Give the form and panel non-transparent surfaces from the app's tokens, with the
+form boundary distinguishable from the surrounding background in every supported theme:
 
 ```css
 .ais-AutocompletePanel {
-  min-width: 320px;
+  min-width: min(320px, calc(100vw - 2rem));
+  max-width: calc(100vw - 2rem);
   left: 0; /* right: 0; left: auto for an input aligned to the right */
 }
 ```

package/docs/algolia-sdk/instantsearch-setup-vue.md

@@ -37,14 +37,16 @@ each index's `sendEvent`.
     >
       <ais-autocomplete>
         <template v-slot="{ currentRefinement, indices, refine }">
+          <label :for="inputId">Search products</label>
           <input
+            :id="inputId"
             type="search"
             role="combobox"
             aria-autocomplete="list"
-            aria-controls="search-panel"
+            :aria-controls="panelId"
             :aria-expanded="isOpen(currentRefinement)"
             :aria-activedescendant="
-              active >= 0 ? `search-option-${active}` : undefined
+              active >= 0 ? optionId(active) : undefined
             "
             :value="currentRefinement"
             @focus="open = true"
@@ -54,16 +56,19 @@ each index's `sendEvent`.
             @keydown.enter.prevent="select(indices, active)"
             @keydown.esc="close"
           />
+          <p class="visually-hidden" aria-live="polite">
+            {{ statusMessage(currentRefinement, indices) }}
+          </p>
           <ul
             v-show="isOpen(currentRefinement)"
-            id="search-panel"
+            :id="panelId"
             class="search-panel"
             role="listbox"
             aria-label="Search results"
           >
             <li
               v-for="(hit, i) in indices[0]?.hits ?? []"
-              :id="`search-option-${i}`"
+              :id="optionId(i)"
               :key="hit.objectID"
               role="option"
               :aria-selected="i === active"
@@ -89,15 +94,28 @@ import {
   ALGOLIA_INDEX_NAME,
 } from '<the project's shared config module>'
 
+const props = defineProps({
+  idPrefix: { type: String, required: true },
+})
 const searchClient = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY)
 const open = ref(false)
 const active = ref(-1)
 const containerRef = ref(null)
 
+const inputId = `${props.idPrefix}-input`
+const panelId = `${props.idPrefix}-panel`
+const optionId = (index) => `${props.idPrefix}-option-${index}`
+
 function isOpen(currentRefinement) {
   return open.value && Boolean(currentRefinement)
 }
 
+function statusMessage(currentRefinement, indices) {
+  if (!isOpen(currentRefinement)) return ''
+  const count = indices[0]?.hits?.length ?? 0
+  return count === 0 ? 'No results' : `${count} search result${count === 1 ? '' : 's'}`
+}
+
 function onInput(refine, event) {
   open.value = true
   active.value = -1
@@ -131,6 +149,11 @@ function onFocusOut(event) {
 </script>
 ```
 
+### Match entity schema
+
+Adapt the label, placeholder, highlighted attributes, result content, and destination to
+the confirmed indexed entity. `products` and `name` above are examples.
+
 Details that break accessibility if changed:
 
 - `role="combobox"` on the `input`, not a wrapper — with `aria-controls` at the popup's
@@ -146,11 +169,42 @@ Details that break accessibility if changed:
   top — it fights `@mousedown.prevent`.
 - `.is-active` needs a visible style, not just `aria-selected` — it is a keyboard user's
   only focus feedback, since focus never leaves the input.
-
-The panel is your own markup with no widget theme to inherit: give `.search-panel` a
-background from the app's theme tokens (never transparent over page content), text
-clearing 4.5:1 against it, `position: absolute` with `min-width: 320px` anchored to the
-input edge it opens from, and a `max-height` with `overflow-y: auto`.
+- Pass a stable, unique `id-prefix` whenever this component is rendered, for example
+  `id-prefix="catalog-search"`. Use a different value for each simultaneous mount so
+  labels and `aria-controls` never point at another instance.
+
+Keep the associated label visible when the layout permits; otherwise use the app's
+existing visually-hidden utility rather than removing it. The persistent `aria-live`
+status above announces result counts and no-results state without moving focus; keep it
+in the app's visually-hidden utility class (`.visually-hidden` is a placeholder for
+whatever the project already uses) so it never shifts the layout it sits in. Surface
+loading and errors through the same status region if the surrounding app exposes those
+states.
+
+Target WCAG 2.2 AA after applying the app's design tokens:
+
+- input, placeholder, and result text clear 4.5:1 contrast;
+- meaningful icons, control boundaries, and focus indicators clear 3:1 contrast;
+- focus is visible and unobscured, and no state relies on color alone;
+- controls have 24 by 24 CSS pixel targets or enough spacing around smaller targets;
+- the experience reflows at a 320 CSS pixel viewport without horizontal page scrolling;
+- any added animation respects `prefers-reduced-motion`.
+
+The panel is your own markup with no widget theme to inherit. Give the input and
+`.search-panel` non-transparent surfaces from the app's tokens, and make the input
+boundary distinguishable from its surrounding background in every supported theme. Use
+`position: absolute`, a 320px minimum when space permits, a viewport cap, an input-edge
+anchor, and a scrollable maximum height:
+
+```css
+.search-panel {
+  min-width: min(320px, calc(100vw - 2rem));
+  max-width: calc(100vw - 2rem);
+  max-height: min(24rem, calc(100vh - 2rem));
+  overflow-y: auto;
+  left: 0; /* right: 0; left: auto for an input aligned to the right */
+}
+```
 
 `indices` supports federated search across indices; this project has one, so `indices[0]`
 is always the one to read.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@algolia/wizard",
-  "version": "0.69.0",
+  "version": "0.71.0",
   "description": "Magically implement Algolia functionality in your codebase",
   "type": "module",
   "engines": {