chore(document): gate auto-capture debug tooling to dev + preview only

[Barnabas A Nsoh (ayinloya)]

User description

What

The document auto-capture debug tooling (live TuningPanel, ROI overlay, verbose detection logs) was exposed in every environment — DocumentAutoCapture hardcoded showDebug = true, so end users would see it in production. This gates it behind a build-time flag so it appears only in dev + preview and is compiled out of production.

How

• __SMILE_DEBUG__ build-time flag injected by the web-components Vite define: true for non-production vite modes (vite dev + Storybook) or when SMILE_DEBUG_BUILD=true; production / npm-publish builds (vite build, no flag) compile it out (fail-safe default).
• utils/debug.ts#isDebugEnabled() is the single source of truth — replaces the hardcoded showDebug and the ?debug URL check in IS_DEBUG_MODE. (A URL param can't drive this: the component runs inside the embed iframe, so a parent-page ?debug never reaches it.)
• deploy-preview.yml sets SMILE_DEBUG_BUILD=true on the web-components build; dev-mobile.sh sets it for the locally-built embed. Prod deploy / publish unchanged.

Verification

• Prod build (no env) vs preview build (SMILE_DEBUG_BUILD=true) produce different bundles; __SMILE_DEBUG__ is fully replaced in the emitted .js (present only in sourcemaps).
• tsc --noEmit + eslint clean on changed files.
• Storybook (dev mode) still shows the panel — existing workflow unchanged.

Base

Targets feat/mobile-capture-adaptive-canny so the diff is only this change (it's branched off that work). When #673 merges, this will retarget to document-capture-new-flow.

🤖 Generated with Claude Code

---

PR Type

Enhancement

---

Description

• Gate debug tooling behind build-time __SMILE_DEBUG__ flag

• Strip TuningPanel/ROI overlay from production builds

• Enable debug in dev, Storybook, and preview deploys only

• Replace hardcoded showDebug = true and URL-param check

---

Diagram Walkthrough

flowchart LR
  ViteConfig["vite.config.ts define"] -- "injects __SMILE_DEBUG__" --> DebugUtil["utils/debug.ts"]
  DebugUtil -- "isDebugEnabled()" --> Component["DocumentAutoCapture.tsx"]
  DebugUtil -- "isDebugEnabled()" --> Hook["useCardDetection.ts"]
  EnvFlag["SMILE_DEBUG_BUILD env var"] -- "true for preview/dev" --> ViteConfig
  ViteConfig -- "false for production" --> DeadCode["Debug code stripped"]

Loading

File Walkthrough

	Relevant files
Enhancement	debug.ts Add build-time debug flag utility                                                packages/web-components/lib/components/document/src/document-auto-capture/utils/debug.ts New utility module exporting isDebugEnabled() function Checks build-time __SMILE_DEBUG__ constant with typeof guard Serves as single source of truth for debug mode across the component +14/-0    useCardDetection.ts Replace URL-param debug check with build flag                        packages/web-components/lib/components/document/src/document-auto-capture/hooks/useCardDetection.ts Replaced URL-param-based IS_DEBUG_MODE with isDebugEnabled() call Removed window.location.search parsing logic Imported isDebugEnabled from the new debug utility +5/-6
Bug fix	DocumentAutoCapture.tsx Use build-time debug flag for showDebug                                    packages/web-components/lib/components/document/src/document-auto-capture/DocumentAutoCapture.tsx Replaced hardcoded showDebug = true with isDebugEnabled() call Imported new isDebugEnabled utility from utils/debug +4/-1
Configuration changes	vite.config.ts Inject __SMILE_DEBUG__ build-time define                                  packages/web-components/vite.config.ts Added debugEnabled variable: true for non-production mode or when SMILE_DEBUG_BUILD=true Injected __SMILE_DEBUG__ into define config with the computed boolean +8/-0      deploy-preview.yml Enable debug build for preview deploys                                      .github/workflows/deploy-preview.yml Added SMILE_DEBUG_BUILD: 'true' env variable to the web-components build step Ensures preview deployments include debug tooling +4/-0      dev-mobile.sh Enable debug build in local dev-mobile script                        previews/scripts/dev-mobile.sh Prefixed web-components build command with SMILE_DEBUG_BUILD=true Added comments explaining the flag's purpose for local dev builds +4/-1

---

---

Need help?

Type /help how to ... in the comments thread for any questions about PR-Agent usage.

Check out the documentation for more information.

[github-actions]

🔍 Semgrep Security Scan Results

✅ No security findings detected by p/security-audit ruleset.

[prfectionist]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 673 - Partially compliant Compliant requirements: (empty - this PR is about gating debug tooling, not implementing the adaptive Canny feature itself) Non-compliant requirements: (empty - this PR builds on top of #673, it doesn't claim to implement those requirements) Requires further human verification: This PR targets the adaptive Canny branch; verify that the debug gating doesn't interfere with the adaptive Canny functionality in dev/preview environments

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🏅 Score: 90

🧪 No relevant tests

🔒 No security concerns identified

🔀 No multiple PR themes

⚡ Recommended focus areas for review Tree-shaking The isDebugEnabled() function returns a value derived from __SMILE_DEBUG__ which is replaced at build time. However, since it's a function call rather than a direct constant reference, verify that the bundler (esbuild/Vite) can actually dead-code-eliminate the debug branches (TuningPanel rendering, verbose logs) in production. If the function isn't inlined, the conditional code may still be included in the production bundle even though it's never executed. export const isDebugEnabled = (): boolean => typeof __SMILE_DEBUG__ !== 'undefined' && __SMILE_DEBUG__ === true; Runtime call isDebugEnabled() is called inside the component body on every render. While cheap, if the intent is compile-time elimination, this pattern may prevent the bundler from stripping the debug JSX. Consider whether the result should be a module-level constant (like in useCardDetection.ts) so the bundler can more easily eliminate dead code paths. const showDebug = isDebugEnabled();

[prfectionist]

Suggestion: Since __SMILE_DEBUG__ is replaced at build time by JSON.stringify(debugEnabled) (which produces the literal true or false), the typeof guard will never trigger at runtime in a properly bundled build — the code becomes typeof true !== 'undefined' && true === true. However, in test runners (Jest/Vitest without the define), __SMILE_DEBUG__ remains an undeclared identifier and typeof __SMILE_DEBUG__ correctly prevents a ReferenceError. This is fine, but wrapping it in a function means it's re-evaluated on every call. Since the value is a compile-time constant, exporting a const directly would allow bundlers to tree-shake dead branches more effectively. [general, importance: 5]

Suggested change

	export const isDebugEnabled = (): boolean =>
	typeof __SMILE_DEBUG__ !== 'undefined' && __SMILE_DEBUG__ === true;
	export const isDebugEnabled: boolean =
	typeof __SMILE_DEBUG__ !== 'undefined' && __SMILE_DEBUG__ === true;

[Copilot]

Pull request overview

This PR gates the document auto-capture debug tooling (TuningPanel, ROI overlay, verbose detection logs) behind a build-time __SMILE_DEBUG__ flag so it’s enabled only for dev + preview builds and intended to be omitted from production bundles.

Changes:

• Add __SMILE_DEBUG__ build-time define in packages/web-components Vite config (dev on by default; preview via SMILE_DEBUG_BUILD=true; production defaults off).
• Introduce a shared isDebugEnabled() helper and route both the UI debug toggle and detection telemetry gating through it.
• Ensure preview deploys and local dev-mobile.sh builds opt into debug tooling via SMILE_DEBUG_BUILD=true.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
previews/scripts/dev-mobile.sh	Sets SMILE_DEBUG_BUILD=true when building web-components for local mobile preview tunneling.
packages/web-components/vite.config.ts	Injects __SMILE_DEBUG__ via Vite define based on mode/env.
packages/web-components/lib/components/document/src/document-auto-capture/utils/debug.ts	Adds isDebugEnabled() utility wrapping the build-time flag.
packages/web-components/lib/components/document/src/document-auto-capture/hooks/useCardDetection.ts	Switches debug telemetry gating from URL params to the build-time debug flag.
packages/web-components/lib/components/document/src/document-auto-capture/DocumentAutoCapture.tsx	Replaces hardcoded showDebug = true with build-time-gated debug enablement.
.github/workflows/deploy-preview.yml	Enables debug tooling in preview bundles by setting SMILE_DEBUG_BUILD: 'true' for the web-components build step.

[github-actions]

This branch has been deployed to s3 / cloudfront.

✅ Preview URL for Smart Camera Web:

https://cdn.smileidentity.com/js/preview-chore/debug-dev-preview-only/smart-camera-web.js

✅ Preview URL for Embed:

https://cdn.smileidentity.com/inline/preview-chore/debug-dev-preview-only/js/script.min.js

✅ Preview URL for Web Client (Sandbox):

https://d1fqqwij8k7ka9.cloudfront.net

✅ Preview URL for Web Client (Production):

https://ddd50hal8wskz.cloudfront.net