diff --git a/example-apps/dashnote/src/components/LoginModal.tsx b/example-apps/dashnote/src/components/LoginModal.tsx
index cb6e2e2..3dda78d 100644
--- a/example-apps/dashnote/src/components/LoginModal.tsx
+++ b/example-apps/dashnote/src/components/LoginModal.tsx
@@ -1,6 +1,8 @@
-import { useEffect, useState, type FormEvent } from "react";
+import { useEffect, useMemo, useState, type FormEvent } from "react";
 
 import { registerContract } from "../dash/contract";
+import { useWifPreview } from "../hooks/useWifPreview";
+import { detectSecretShape } from "../lib/detectSecretShape";
 import { errorMessage } from "../lib/logger";
 import { useSession } from "../session/useSession";
 import { Modal } from "./Modal";
@@ -13,7 +15,7 @@ export interface LoginModalProps {
 
 export function LoginModal({ open, onClose }: LoginModalProps) {
   const session = useSession();
-  const [mnemonic, setMnemonic] = useState("");
+  const [secret, setSecret] = useState("");
   const [identityIndex, setIdentityIndex] = useState("0");
   const [contractInput, setContractInput] = useState(session.contractId ?? "");
   const [error, setError] = useState<string | null>(null);
@@ -26,6 +28,17 @@ export function LoginModal({ open, onClose }: LoginModalProps) {
   const showRememberedPanel = Boolean(
     session.rememberedIdentityId && !useDifferentIdentity,
   );
+  // Detect what the user pasted so we can hide the identity-index field for
+  // single-key WIF input (where DIP-13 derivation doesn't apply).
+  const secretShape = useMemo(
+    () => (secret.trim() ? detectSecretShape(secret) : null),
+    [secret],
+  );
+  const isWifInput = secretShape === "wif";
+  const wifPreview = useWifPreview(session.sdk, secret, isWifInput);
+  const previewBlocksLogin =
+    wifPreview.status === "wrong-purpose" ||
+    wifPreview.status === "key-disabled";
 
   useEffect(() => {
     setContractInput(session.contractId ?? "");
@@ -36,7 +49,7 @@ export function LoginModal({ open, onClose }: LoginModalProps) {
       setRememberMe(true);
       setUseDifferentIdentity(false);
       setError(null);
-      setMnemonic("");
+      setSecret("");
     }
   }, [open]);
 
@@ -69,11 +82,11 @@ export function LoginModal({ open, onClose }: LoginModalProps) {
     setSubmitting(true);
     try {
       const index = Number.parseInt(identityIndex, 10);
-      await session.login(mnemonic, {
+      await session.login(secret, {
         identityIndex: Number.isNaN(index) ? 0 : index,
         rememberMe,
       });
-      setMnemonic("");
+      setSecret("");
       onClose();
     } catch (err) {
       setError(errorMessage(err));
@@ -240,7 +253,9 @@ export function LoginModal({ open, onClose }: LoginModalProps) {
 
           <label className="flex flex-col gap-1">
             <span className="text-[10px] font-semibold uppercase tracking-[0.12em] text-ink-4">
-              {showRememberedPanel ? "Mnemonic" : "Identity Mnemonic"}
+              {showRememberedPanel
+                ? "Mnemonic or Private Key"
+                : "Identity Mnemonic or Private Key"}
             </span>
             {!showRememberedPanel && (
               <p className="text-[11px] text-ink-3">
@@ -260,15 +275,58 @@ export function LoginModal({ open, onClose }: LoginModalProps) {
               type="password"
               autoComplete="off"
               required
-              value={mnemonic}
-              onChange={(event) => setMnemonic(event.target.value)}
-              placeholder={
-                showRememberedPanel
-                  ? "Enter the mnemonic for this identity"
-                  : "mnemonic phrase"
-              }
+              value={secret}
+              onChange={(event) => setSecret(event.target.value)}
+              placeholder="Mnemonic phrase or WIF private key (high/critical)"
               className="rounded-md border border-line bg-bg px-3 py-2 text-[13px] text-ink outline-none transition focus:border-accent-dim"
             />
+            {isWifInput && wifPreview.status !== "idle" && (
+              <div
+                data-testid="wif-preview"
+                aria-live="polite"
+                className="mt-1 min-h-[1.5em] text-[11px]"
+              >
+                {wifPreview.status === "checking" && (
+                  <span className="text-ink-4">Checking…</span>
+                )}
+                {wifPreview.status === "resolved" && (
+                  <span className="text-ink-3">
+                    ✓ Identity{" "}
+                    <span className="font-mono text-accent">
+                      {wifPreview.dpnsName
+                        ? `${wifPreview.dpnsName}.dash`
+                        : `${wifPreview.identityId.slice(0, 8)}…${wifPreview.identityId.slice(-4)}`}
+                    </span>
+                  </span>
+                )}
+                {wifPreview.status === "wrong-purpose" && (
+                  <span className="text-[color:var(--color-danger)]">
+                    Found identity{" "}
+                    <span className="font-mono">
+                      {wifPreview.dpnsName
+                        ? `${wifPreview.dpnsName}.dash`
+                        : `${wifPreview.identityId.slice(0, 8)}…${wifPreview.identityId.slice(-4)}`}
+                    </span>
+                    , but this is a{" "}
+                    {wifPreview.purposeName === "AUTHENTICATION"
+                      ? `${wifPreview.securityLevelName} authentication`
+                      : wifPreview.purposeName}{" "}
+                    key — paste a HIGH or CRITICAL authentication key instead.
+                  </span>
+                )}
+                {wifPreview.status === "key-disabled" && (
+                  <span className="text-[color:var(--color-danger)]">
+                    The matching key on identity{" "}
+                    <span className="font-mono">
+                      {wifPreview.dpnsName
+                        ? `${wifPreview.dpnsName}.dash`
+                        : `${wifPreview.identityId.slice(0, 8)}…${wifPreview.identityId.slice(-4)}`}
+                    </span>{" "}
+                    has been disabled.
+                  </span>
+                )}
+              </div>
+            )}
           </label>
 
           {session.rememberedIdentityId && (
@@ -320,18 +378,20 @@ export function LoginModal({ open, onClose }: LoginModalProps) {
 
           {showAdvanced && (
             <div className="flex flex-col gap-4 rounded-md border border-line bg-bg/40 p-3">
-              <label className="flex flex-col gap-1">
-                <span className="text-[10px] font-semibold uppercase tracking-[0.12em] text-ink-4">
-                  Identity index
-                </span>
-                <input
-                  type="number"
-                  min={0}
-                  value={identityIndex}
-                  onChange={(event) => setIdentityIndex(event.target.value)}
-                  className="w-24 rounded-md border border-line bg-bg px-3 py-2 text-[13px] text-ink outline-none transition focus:border-accent-dim"
-                />
-              </label>
+              {!isWifInput && (
+                <label className="flex flex-col gap-1">
+                  <span className="text-[10px] font-semibold uppercase tracking-[0.12em] text-ink-4">
+                    Identity index
+                  </span>
+                  <input
+                    type="number"
+                    min={0}
+                    value={identityIndex}
+                    onChange={(event) => setIdentityIndex(event.target.value)}
+                    className="w-24 rounded-md border border-line bg-bg px-3 py-2 text-[13px] text-ink outline-none transition focus:border-accent-dim"
+                  />
+                </label>
+              )}
 
               <div className="flex flex-col gap-2">
                 <span className="text-[10px] font-semibold uppercase tracking-[0.12em] text-ink-4">
@@ -363,15 +423,14 @@ export function LoginModal({ open, onClose }: LoginModalProps) {
           )}
 
           <p className="text-[11px] text-ink-4">
-            Your mnemonic stays in browser memory and is never sent or saved.
-            Only the public identity ID is persisted, and only when “Remember
-            me” is checked.
+            Your secret never leaves this browser. Only the public identity ID
+            is stored when this identity is remembered on this device.
           </p>
 
           <div className="flex gap-2 pt-1">
             <button
               type="submit"
-              disabled={submitting || !mnemonic.trim()}
+              disabled={submitting || !secret.trim() || previewBlocksLogin}
               className="flex-1 rounded-md bg-accent px-4 py-2 text-[13px] font-semibold text-bg transition hover:bg-accent-dim disabled:cursor-not-allowed disabled:bg-surface-2 disabled:text-ink-4"
             >
               {submitting ? "Connecting…" : "Login"}
diff --git a/example-apps/dashnote/src/dash/loginWithPrivateKey.ts b/example-apps/dashnote/src/dash/loginWithPrivateKey.ts
new file mode 100644
index 0000000..a9376ef
--- /dev/null
+++ b/example-apps/dashnote/src/dash/loginWithPrivateKey.ts
@@ -0,0 +1,306 @@
+import {
+  IdentitySigner,
+  PrivateKey,
+  Purpose,
+  SecurityLevel,
+} from "@dashevo/evo-sdk";
+
+import type { DashAuth, DashSdk } from "./types";
+
+export class UnknownIdentityError extends Error {
+  constructor() {
+    super("No identity is registered with this key on testnet.");
+    this.name = "UnknownIdentityError";
+  }
+}
+
+export class WrongKeyPurposeError extends Error {
+  identityId: string;
+  purposeName: string;
+  securityLevelName: string;
+
+  constructor(
+    identityId: string,
+    purposeName: string,
+    securityLevelName: string,
+  ) {
+    super(
+      `Found identity ${identityId}, but this key can't sign document or contract operations. Paste a HIGH or CRITICAL authentication key instead.`,
+    );
+    this.name = "WrongKeyPurposeError";
+    this.identityId = identityId;
+    this.purposeName = purposeName;
+    this.securityLevelName = securityLevelName;
+  }
+}
+
+export class KeyDisabledError extends Error {
+  identityId: string;
+
+  constructor(identityId: string) {
+    super(`The matching key on identity ${identityId} has been disabled.`);
+    this.name = "KeyDisabledError";
+    this.identityId = identityId;
+  }
+}
+
+export class InvalidPrivateKeyError extends Error {
+  constructor() {
+    super("This doesn't look like a valid private key (WIF).");
+    this.name = "InvalidPrivateKeyError";
+  }
+}
+
+interface IdentityJsonKey {
+  id: number;
+  purpose: number;
+  securityLevel: number;
+  data?: string;
+  disabled?: boolean;
+  disabledAt?: number | string | null;
+}
+
+interface IdentityJson {
+  publicKeys?: IdentityJsonKey[];
+}
+
+interface IdentityLike {
+  toJSON?: () => IdentityJson;
+  id: { toString(): string } | string;
+  getPublicKeyById?: (keyId: number) => unknown;
+}
+
+/**
+ * Compare two byte arrays for equality.
+ */
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Decode a public-key data field from `identity.toJSON()`.
+ *
+ * Dash Platform's JSON encoding for bytes has historically been base64,
+ * but some versions emit hex. We try base64 first (preferred), then hex,
+ * before giving up. Returning null lets the caller skip a key it can't
+ * compare rather than aborting.
+ */
+function tryDecodeKeyData(data: string): Uint8Array | null {
+  if (typeof data !== "string" || data.length === 0) return null;
+
+  if (/^[0-9a-fA-F]+$/.test(data) && data.length % 2 === 0) {
+    try {
+      const bytes = new Uint8Array(data.length / 2);
+      for (let i = 0; i < bytes.length; i += 1) {
+        bytes[i] = parseInt(data.slice(i * 2, i * 2 + 2), 16);
+      }
+      return bytes;
+    } catch {
+      // fall through to base64
+    }
+  }
+
+  try {
+    const binary = atob(data);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  } catch {
+    return null;
+  }
+}
+
+// Document and contract state transitions require HIGH or CRITICAL auth.
+// MASTER (key 0) can only sign identity-update transitions, so a user who
+// pastes their master WIF would log in successfully but fail at the first
+// note write — reject up front with a clear message instead.
+const AUTH_SECURITY_LEVELS = new Set<number>([
+  SecurityLevel.HIGH as unknown as number,
+  SecurityLevel.CRITICAL as unknown as number,
+]);
+
+const PURPOSE_NAMES: Record<number, string> = {
+  [Purpose.AUTHENTICATION as unknown as number]: "AUTHENTICATION",
+  [Purpose.ENCRYPTION as unknown as number]: "ENCRYPTION",
+  [Purpose.TRANSFER as unknown as number]: "TRANSFER",
+};
+
+const SECURITY_LEVEL_NAMES: Record<number, string> = {
+  [SecurityLevel.MASTER as unknown as number]: "MASTER",
+  [SecurityLevel.CRITICAL as unknown as number]: "CRITICAL",
+  [SecurityLevel.HIGH as unknown as number]: "HIGH",
+  [SecurityLevel.MEDIUM as unknown as number]: "MEDIUM",
+};
+
+function purposeName(purpose: number): string {
+  return PURPOSE_NAMES[purpose] ?? `PURPOSE_${purpose}`;
+}
+
+function securityLevelName(level: number): string {
+  return SECURITY_LEVEL_NAMES[level] ?? `LEVEL_${level}`;
+}
+
+interface ResolvedWifIdentity {
+  identity: IdentityLike;
+  identityId: string;
+  matched: IdentityJsonKey;
+  identityKey: unknown;
+}
+
+/**
+ * Resolve which identity a WIF private key belongs to and which key on that
+ * identity it matches, without building a signer. Performs every check the
+ * full login does (WIF parse, identity lookup, key-purpose / disabled / level
+ * validation) and throws the same error types — this is the shared core for
+ * both eager preview and the actual login.
+ *
+ * The signer construction is split out so the preview path can avoid touching
+ * the WASM signer until the user commits to logging in.
+ */
+export async function resolveIdentityFromWif(
+  sdk: DashSdk,
+  wif: string,
+): Promise<ResolvedWifIdentity> {
+  let privateKey: PrivateKey;
+  try {
+    privateKey = PrivateKey.fromWIF(wif);
+  } catch {
+    throw new InvalidPrivateKeyError();
+  }
+
+  const pubKeyHash = privateKey.getPublicKeyHash();
+
+  const identity = (await sdk.identities.byPublicKeyHash(
+    pubKeyHash as never,
+  )) as IdentityLike | undefined | null;
+  if (!identity) {
+    throw new UnknownIdentityError();
+  }
+
+  const identityId =
+    typeof identity.id === "string" ? identity.id : identity.id.toString();
+
+  const json = identity.toJSON?.();
+  const publicKeys = json?.publicKeys ?? [];
+  if (publicKeys.length === 0) {
+    // Shouldn't happen — byPublicKeyHash matched, so a key exists. Treat as
+    // an unexpected SDK response and fail closed.
+    throw new UnknownIdentityError();
+  }
+
+  // Get the public key bytes our WIF derives, so we can identify which
+  // entry in publicKeys[] is ours.
+  const pkAny = privateKey as unknown as {
+    getPublicKey?: () => unknown;
+    toPublicKey?: () => unknown;
+  };
+  const ourPubKey = pkAny.getPublicKey
+    ? pkAny.getPublicKey()
+    : pkAny.toPublicKey?.();
+  const ourPubKeyBytes: Uint8Array | null = ourPubKey
+    ? extractPubKeyBytes(ourPubKey)
+    : null;
+
+  const matched = publicKeys.find((entry) => {
+    if (!entry.data || !ourPubKeyBytes) return false;
+    const entryBytes = tryDecodeKeyData(entry.data);
+    return entryBytes ? bytesEqual(entryBytes, ourPubKeyBytes) : false;
+  });
+  if (!matched) {
+    // Hash matched but we couldn't reconcile against any entry in the JSON
+    // (likely a data-encoding skew). Treat as unexpected and fail closed
+    // rather than silently picking the first key.
+    throw new UnknownIdentityError();
+  }
+
+  if (matched.disabled === true || matched.disabledAt) {
+    throw new KeyDisabledError(identityId);
+  }
+
+  const purposeValue = matched.purpose;
+  const securityLevelValue = matched.securityLevel;
+  const isAuthPurpose =
+    purposeValue === (Purpose.AUTHENTICATION as unknown as number);
+  const isAuthLevel = AUTH_SECURITY_LEVELS.has(securityLevelValue);
+  if (!isAuthPurpose || !isAuthLevel) {
+    throw new WrongKeyPurposeError(
+      identityId,
+      purposeName(purposeValue),
+      securityLevelName(securityLevelValue),
+    );
+  }
+
+  const identityKey = identity.getPublicKeyById?.(matched.id);
+  return { identity, identityId, matched, identityKey };
+}
+
+/**
+ * Look up an identity from a WIF private key and prepare a one-key signer
+ * for auth-purpose operations.
+ *
+ * Thin wrapper around `resolveIdentityFromWif` that adds signer construction.
+ */
+export async function loginWithPrivateKey(
+  sdk: DashSdk,
+  wif: string,
+): Promise<DashAuth & { identityId: string }> {
+  const resolved = await resolveIdentityFromWif(sdk, wif);
+  const signer = new IdentitySigner();
+  signer.addKeyFromWif(wif);
+
+  return {
+    identity: resolved.identity as never,
+    identityKey: resolved.identityKey as never,
+    signer,
+    identityId: resolved.identityId,
+  };
+}
+
+/**
+ * Pull the raw compressed public key bytes from a `PrivateKey.toPublicKey()`
+ * result. The SDK exposes a few encoders depending on version (toBytes(),
+ * toBuffer(), toString('hex'), etc.) — we try each in order.
+ */
+function extractPubKeyBytes(pubKey: unknown): Uint8Array | null {
+  const candidate = pubKey as {
+    toBytes?: () => Uint8Array | ArrayLike<number>;
+    toBuffer?: () => Uint8Array | ArrayLike<number>;
+    toString?: (encoding?: string) => string;
+  };
+
+  if (typeof candidate.toBytes === "function") {
+    try {
+      return new Uint8Array(candidate.toBytes() as ArrayLike<number>);
+    } catch {
+      // fall through
+    }
+  }
+  if (typeof candidate.toBuffer === "function") {
+    try {
+      return new Uint8Array(candidate.toBuffer() as ArrayLike<number>);
+    } catch {
+      // fall through
+    }
+  }
+  if (typeof candidate.toString === "function") {
+    try {
+      const hex = candidate.toString("hex");
+      if (typeof hex === "string" && /^[0-9a-fA-F]+$/.test(hex)) {
+        const bytes = new Uint8Array(hex.length / 2);
+        for (let i = 0; i < bytes.length; i += 1) {
+          bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+        }
+        return bytes;
+      }
+    } catch {
+      // fall through
+    }
+  }
+  return null;
+}
diff --git a/example-apps/dashnote/src/dash/types.ts b/example-apps/dashnote/src/dash/types.ts
index a14ab66..bca572d 100644
--- a/example-apps/dashnote/src/dash/types.ts
+++ b/example-apps/dashnote/src/dash/types.ts
@@ -73,6 +73,9 @@ export interface DashSdk {
   };
   identities: {
     nonce(identityId: string): Promise<bigint | null | undefined>;
+    byPublicKeyHash(
+      publicKeyHash: Uint8Array,
+    ): Promise<Identity | null | undefined>;
   };
   dpns: {
     username(identityId: string): Promise<string | null | undefined>;
diff --git a/example-apps/dashnote/src/hooks/useWifPreview.ts b/example-apps/dashnote/src/hooks/useWifPreview.ts
new file mode 100644
index 0000000..f70b4b7
--- /dev/null
+++ b/example-apps/dashnote/src/hooks/useWifPreview.ts
@@ -0,0 +1,150 @@
+import { useEffect, useState } from "react";
+
+import { resolveDpnsName } from "../dash/resolveDpnsName";
+import type { DashSdk } from "../dash/types";
+import { looksLikeWif } from "../lib/detectSecretShape";
+
+// loginWithPrivateKey transitively imports @dashevo/evo-sdk (~8MB WASM).
+// Pulling it in statically here would defeat SessionContext's lazy-load and
+// drag the SDK chunk into the app shell. Defer to the post-debounce callback,
+// where we've already committed to a network call.
+type LoginModule = typeof import("../dash/loginWithPrivateKey");
+let loginModulePromise: Promise<LoginModule> | null = null;
+function loadLoginModule(): Promise<LoginModule> {
+  if (!loginModulePromise) {
+    loginModulePromise = import("../dash/loginWithPrivateKey").catch((err) => {
+      // Clear the cache on failure so a subsequent attempt can retry the
+      // chunk fetch instead of awaiting a permanently-rejected promise.
+      loginModulePromise = null;
+      throw err;
+    });
+  }
+  return loginModulePromise;
+}
+
+export type WifPreviewState =
+  | { status: "idle" }
+  | { status: "checking" }
+  | { status: "resolved"; identityId: string; dpnsName: string | null }
+  | {
+      status: "wrong-purpose";
+      identityId: string;
+      dpnsName: string | null;
+      purposeName: string;
+      securityLevelName: string;
+    }
+  | { status: "key-disabled"; identityId: string; dpnsName: string | null };
+
+const IDLE: WifPreviewState = { status: "idle" };
+const CHECKING: WifPreviewState = { status: "checking" };
+const DEBOUNCE_MS = 400;
+
+/**
+ * Eagerly resolves a pasted WIF to its owning identity (and DPNS name) so
+ * the user gets pre-submit confirmation and "wrong key type" feedback before
+ * hitting Login. Network lookup is gated on a cheap structural check
+ * (`looksLikeWif`) plus a debounce — partial input never triggers a request.
+ *
+ * Errors from resolution other than recognized "actionable" ones (wrong
+ * purpose, disabled key) are silently downgraded to `idle`: the user hasn't
+ * committed to login yet, so we don't surface UnknownIdentityError or network
+ * failures as UI errors. The actual login path will surface them on submit.
+ *
+ * Resolution state is component-local: changing the WIF cancels any in-flight
+ * resolver and clears the prior result. We do NOT cache resolved outcomes
+ * across renders — keeping a Map of pasted secrets keyed by raw WIF would
+ * extend secret retention beyond the form lifecycle for no real UX win
+ * (re-pasting the exact same WIF is rare).
+ */
+export function useWifPreview(
+  sdk: DashSdk | null,
+  secret: string,
+  enabled: boolean,
+): WifPreviewState {
+  const trimmed = secret.trim();
+  const gateOk = enabled && Boolean(sdk) && looksLikeWif(trimmed);
+
+  // The resolver tags its result with the WIF that produced it; if `trimmed`
+  // changes between scheduling and rendering, we ignore the stale result at
+  // the bottom of this hook. This avoids any setState in the effect body.
+  // Note: `wif` here is component-local state — it lives only as long as the
+  // input does, matching the lifetime of `secret` in the parent component.
+  const [resolved, setResolved] = useState<{
+    wif: string;
+    state: WifPreviewState;
+  } | null>(null);
+
+  useEffect(() => {
+    if (!gateOk) return;
+    let cancelled = false;
+    const timer = window.setTimeout(async () => {
+      if (cancelled) return;
+      let next: WifPreviewState = IDLE;
+      let mod: LoginModule | null = null;
+      try {
+        mod = await loadLoginModule();
+        if (cancelled) return;
+        const result = await mod.resolveIdentityFromWif(sdk!, trimmed);
+        let dpns: string | null = null;
+        try {
+          dpns = await resolveDpnsName(sdk!, result.identityId);
+        } catch {
+          dpns = null;
+        }
+        next = {
+          status: "resolved",
+          identityId: result.identityId,
+          dpnsName: dpns,
+        };
+      } catch (err) {
+        // mod is null only if loadLoginModule itself rejected (chunk fetch
+        // failure / offline). Treat that as an idle outcome — same silent
+        // policy we apply to UnknownIdentity and network blips.
+        if (
+          mod &&
+          (err instanceof mod.WrongKeyPurposeError ||
+            err instanceof mod.KeyDisabledError)
+        ) {
+          // We have an identity ID — resolve its DPNS name so the warning
+          // can show the user-friendly handle instead of a truncated ID.
+          let dpns: string | null = null;
+          try {
+            dpns = await resolveDpnsName(sdk!, err.identityId);
+          } catch {
+            dpns = null;
+          }
+          if (err instanceof mod.WrongKeyPurposeError) {
+            next = {
+              status: "wrong-purpose",
+              identityId: err.identityId,
+              dpnsName: dpns,
+              purposeName: err.purposeName,
+              securityLevelName: err.securityLevelName,
+            };
+          } else {
+            next = {
+              status: "key-disabled",
+              identityId: err.identityId,
+              dpnsName: dpns,
+            };
+          }
+        } else {
+          // UnknownIdentityError, network failure, import failure, or any
+          // other unexpected error — stay silent until the user submits.
+          next = IDLE;
+        }
+      }
+      if (cancelled) return;
+      setResolved({ wif: trimmed, state: next });
+    }, DEBOUNCE_MS);
+
+    return () => {
+      cancelled = true;
+      window.clearTimeout(timer);
+    };
+  }, [sdk, trimmed, gateOk]);
+
+  if (!gateOk) return IDLE;
+  if (resolved && resolved.wif === trimmed) return resolved.state;
+  return CHECKING;
+}
diff --git a/example-apps/dashnote/src/lib/detectSecretShape.ts b/example-apps/dashnote/src/lib/detectSecretShape.ts
new file mode 100644
index 0000000..9dd6beb
--- /dev/null
+++ b/example-apps/dashnote/src/lib/detectSecretShape.ts
@@ -0,0 +1,31 @@
+/**
+ * Decide whether a pasted secret is a BIP39 mnemonic or a WIF private key.
+ *
+ * BIP39 mnemonics are space-separated word lists; WIF keys are base58-encoded
+ * with no whitespace. The two formats don't overlap, so a whitespace check is
+ * a sufficient discriminator. The downstream parser does the real validation.
+ */
+export type SecretShape = "mnemonic" | "wif";
+
+export function detectSecretShape(input: string): SecretShape {
+  return /\s/.test(input.trim()) ? "mnemonic" : "wif";
+}
+
+// Bitcoin/Dash base58 alphabet (no 0, O, I, l).
+const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]+$/;
+
+/**
+ * Cheap, local "looks like a WIF" check used to gate eager identity lookup.
+ *
+ * Catches obviously-incomplete input (still typing, wrong charset, wrong
+ * length) without invoking the WASM PrivateKey parser. Returning true does
+ * NOT mean the WIF is valid — only that it's worth handing to the parser.
+ * Authoritative validation (checksum, version byte) is done downstream by
+ * `PrivateKey.fromWIF`.
+ */
+export function looksLikeWif(input: string): boolean {
+  const trimmed = input.trim();
+  // Compressed WIF is 52 chars, uncompressed is 51. Anything else is partial.
+  if (trimmed.length !== 51 && trimmed.length !== 52) return false;
+  return BASE58_RE.test(trimmed);
+}
diff --git a/example-apps/dashnote/src/session/SessionContext.tsx b/example-apps/dashnote/src/session/SessionContext.tsx
index 1ed4b59..e79189e 100644
--- a/example-apps/dashnote/src/session/SessionContext.tsx
+++ b/example-apps/dashnote/src/session/SessionContext.tsx
@@ -15,6 +15,7 @@ import {
 } from "../dash/contract";
 import { resolveDpnsName } from "../dash/resolveDpnsName";
 import type { DashKeyManager, DashSdk } from "../dash/types";
+import { detectSecretShape } from "../lib/detectSecretShape";
 import { errorMessage, type Logger } from "../lib/logger";
 import { clearCachedNotes } from "../lib/notesCache";
 import {
@@ -22,6 +23,7 @@ import {
   loadRememberedIdentity,
   saveRememberedIdentity,
 } from "../lib/rememberedIdentity";
+import { keyManagerFromKey } from "./keyManagerFromKey";
 
 // The SDK + IdentityKeyManager pull in @dashevo/evo-sdk (and its ~8MB WASM
 // bundle), so we load them lazily on first use to keep the app shell off
@@ -68,7 +70,7 @@ export interface SessionValue {
   dpnsName: string | null;
   setContractId: (id: string | null) => void;
   log: Logger;
-  login: (mnemonic: string, options?: LoginOptions) => Promise<void>;
+  login: (secret: string, options?: LoginOptions) => Promise<void>;
   enterReadOnly: () => Promise<void>;
   viewAsRemembered: () => Promise<void>;
   forgetIdentity: () => void;
@@ -141,23 +143,50 @@ export function SessionProvider({ children }: { children: ReactNode }) {
   }, [log]);
 
   const login = useCallback(
-    async (mnemonic: string, options: LoginOptions = {}) => {
+    async (secret: string, options: LoginOptions = {}) => {
       const { identityIndex = 0, rememberMe = false } = options;
-      const trimmed = mnemonic.trim();
-      if (!trimmed) throw new Error("Mnemonic is required.");
+      const trimmed = secret.trim();
+      if (!trimmed) throw new Error("Secret is required.");
+      // Snapshot session state so a failed login can restore the user's
+      // prior context instead of clobbering it. Without this, mistyping a
+      // key while in browsing/authenticated mode silently logs the user out.
+      const priorStatus = status;
+      const priorKeyManager = keyManager;
+      const priorIdentityId = identityId;
+      const priorDpnsName = dpnsName;
       setError(null);
       try {
         const connected = sdk ?? (await connect());
-        const { IdentityKeyManager } = await loadSdkModule();
-        const manager = await IdentityKeyManager.create({
-          sdk: connected as never,
-          mnemonic: trimmed,
-          network: "testnet",
-          identityIndex,
-        });
-        setKeyManager(manager);
-        const resolvedId = manager.identityId ?? null;
-        setIdentityId(resolvedId);
+
+        // Detect whether the user pasted a mnemonic or a WIF private key
+        // and dispatch accordingly. identityIndex only applies to mnemonic
+        // input (DIP-13 derivation); a single WIF identifies one key
+        // directly so the index is irrelevant in that path.
+        const shape = detectSecretShape(trimmed);
+
+        let resolvedKeyManager: DashKeyManager;
+        if (shape === "mnemonic") {
+          const { IdentityKeyManager } = await loadSdkModule();
+          resolvedKeyManager = (await IdentityKeyManager.create({
+            sdk: connected as never,
+            mnemonic: trimmed,
+            network: "testnet",
+            identityIndex,
+          })) as unknown as DashKeyManager;
+        } else {
+          // Dynamic import keeps loginWithPrivateKey (and its transitive
+          // @dashevo/evo-sdk dependency) out of the app shell. The mnemonic
+          // branch already pays the SDK fetch via loadSdkModule(); for WIF
+          // we fetch this module on first use here.
+          const { loginWithPrivateKey } =
+            await import("../dash/loginWithPrivateKey");
+          const auth = await loginWithPrivateKey(connected, trimmed);
+          resolvedKeyManager = keyManagerFromKey(auth.identityId, auth);
+        }
+
+        setKeyManager(resolvedKeyManager);
+        const resolvedId = resolvedKeyManager.identityId ?? null;
+        setIdentityId(resolvedId ?? null);
         setStatus("authenticated");
         log(`Identity resolved: ${resolvedId ?? "(unknown)"}`, "success");
 
@@ -184,12 +213,34 @@ export function SessionProvider({ children }: { children: ReactNode }) {
       } catch (err) {
         const message = errorMessage(err);
         setError(message);
-        setStatus("error");
+        // Restore prior session state. If the user was already authenticated
+        // (e.g. they opened Settings and pasted a bad secret), keep them
+        // logged in — a typo shouldn't demote an active session. Otherwise,
+        // prefer landing in browsing mode if a remembered identity exists,
+        // so a failed key-swap still shows the remembered identity panel
+        // instead of the logged-out form.
+        const remembered = loadRememberedIdentity();
+        if (priorStatus === "authenticated" && priorKeyManager) {
+          setKeyManager(priorKeyManager);
+          setIdentityId(priorIdentityId);
+          setDpnsName(priorDpnsName);
+          setStatus(priorStatus);
+        } else if (remembered) {
+          setKeyManager(null);
+          setIdentityId(remembered.id);
+          setDpnsName(remembered.name ?? null);
+          setStatus("browsing");
+        } else {
+          setKeyManager(priorKeyManager);
+          setIdentityId(priorIdentityId);
+          setDpnsName(priorDpnsName);
+          setStatus(priorStatus);
+        }
         log(`Login failed: ${message}`, "error");
         throw err;
       }
     },
-    [sdk, connect, log],
+    [sdk, status, keyManager, identityId, dpnsName, connect, log],
   );
 
   const enterReadOnly = useCallback(async () => {
diff --git a/example-apps/dashnote/src/session/keyManagerFromKey.ts b/example-apps/dashnote/src/session/keyManagerFromKey.ts
new file mode 100644
index 0000000..c91042d
--- /dev/null
+++ b/example-apps/dashnote/src/session/keyManagerFromKey.ts
@@ -0,0 +1,19 @@
+import type { DashAuth, DashKeyManager } from "../dash/types";
+
+/**
+ * Build a DashKeyManager-shaped object from a pre-resolved auth triple.
+ *
+ * Used by the WIF login flow: `loginWithPrivateKey` already located the
+ * identity and built a one-key signer, so getAuth() just hands the cached
+ * triple back. This lets `src/dash/*` helpers consume WIF-based sessions
+ * without a separate code path.
+ */
+export function keyManagerFromKey(
+  identityId: string,
+  auth: DashAuth,
+): DashKeyManager {
+  return {
+    identityId,
+    getAuth: async () => auth,
+  };
+}
diff --git a/example-apps/dashnote/test/LoginModal.test.tsx b/example-apps/dashnote/test/LoginModal.test.tsx
index bd6f765..a36c4ee 100644
--- a/example-apps/dashnote/test/LoginModal.test.tsx
+++ b/example-apps/dashnote/test/LoginModal.test.tsx
@@ -12,10 +12,13 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { LoginModal } from "../src/components/LoginModal";
 
-const { mockUseSession, mockRegisterContract } = vi.hoisted(() => ({
-  mockUseSession: vi.fn(),
-  mockRegisterContract: vi.fn(),
-}));
+const { mockUseSession, mockRegisterContract, mockUseWifPreview } = vi.hoisted(
+  () => ({
+    mockUseSession: vi.fn(),
+    mockRegisterContract: vi.fn(),
+    mockUseWifPreview: vi.fn(),
+  }),
+);
 
 vi.mock("../src/session/useSession", () => ({
   useSession: mockUseSession,
@@ -25,6 +28,14 @@ vi.mock("../src/dash/contract", () => ({
   registerContract: mockRegisterContract,
 }));
 
+// Mocked so LoginModal's preview-rendering branches can be exercised
+// independently of the hook's debounce/network/cache logic (which has its
+// own test file). Each test sets the return value to the state it cares
+// about. Default: idle.
+vi.mock("../src/hooks/useWifPreview", () => ({
+  useWifPreview: mockUseWifPreview,
+}));
+
 interface SessionOverrides {
   status?: string;
   dpnsName?: string | null;
@@ -64,6 +75,8 @@ function makeSession(overrides: SessionOverrides = {}) {
 beforeEach(() => {
   mockUseSession.mockReset();
   mockRegisterContract.mockReset();
+  mockUseWifPreview.mockReset();
+  mockUseWifPreview.mockReturnValue({ status: "idle" });
 });
 
 afterEach(() => {
@@ -296,7 +309,7 @@ describe("LoginModal", () => {
     expect(identityField.value).toBe("remembered-identity-id");
 
     const mnemonicField = screen.getByPlaceholderText(
-      /enter the mnemonic for this identity/i,
+      /mnemonic phrase or wif private key/i,
     );
     expect(
       identityField.compareDocumentPosition(mnemonicField) &
@@ -330,7 +343,7 @@ describe("LoginModal", () => {
     render(<LoginModal open onClose={vi.fn()} />);
 
     const mnemonicField = screen.getByPlaceholderText(
-      /enter the mnemonic for this identity/i,
+      /mnemonic phrase or wif private key/i,
     );
     const actions = screen.getByTestId("remembered-identity-actions");
     expect(
@@ -656,4 +669,186 @@ describe("LoginModal", () => {
       expect(setContractId).toHaveBeenCalledWith("new-contract-id");
     });
   });
+
+  it("shows the identity-index field for mnemonic input under Advanced settings", () => {
+    mockUseSession.mockReturnValue(makeSession());
+    render(<LoginModal open onClose={vi.fn()} />);
+
+    fireEvent.change(screen.getByPlaceholderText(/mnemonic phrase/i), {
+      target: { value: "abandon abandon abandon" },
+    });
+    fireEvent.click(screen.getByText(/advanced settings/i));
+
+    expect(screen.queryByRole("spinbutton")).not.toBeNull();
+  });
+
+  it("hides the identity-index field when the input parses as a WIF", () => {
+    mockUseSession.mockReturnValue(makeSession());
+    render(<LoginModal open onClose={vi.fn()} />);
+
+    fireEvent.change(screen.getByPlaceholderText(/mnemonic phrase/i), {
+      target: { value: "cVHcfvcWNc7DvqaPCwM6Z3DqZ" },
+    });
+    fireEvent.click(screen.getByText(/advanced settings/i));
+
+    expect(screen.queryByRole("spinbutton")).toBeNull();
+  });
+
+  it("forwards a WIF input verbatim to session.login", async () => {
+    const login = vi.fn().mockResolvedValue(undefined);
+    mockUseSession.mockReturnValue(makeSession({ login }));
+
+    render(<LoginModal open onClose={vi.fn()} />);
+
+    fireEvent.change(screen.getByPlaceholderText(/mnemonic phrase/i), {
+      target: { value: "cVHcfvcWNc7DvqaPCwM6Z3DqZ" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /^login$/i }));
+
+    await waitFor(() => {
+      expect(login).toHaveBeenCalledWith("cVHcfvcWNc7DvqaPCwM6Z3DqZ", {
+        identityIndex: 0,
+        rememberMe: true,
+      });
+    });
+  });
+
+  describe("WIF eager-preview rendering", () => {
+    // The preview region only mounts when the secret is detected as WIF
+    // shape (no whitespace). Each test types a WIF-shaped string and lets
+    // the mocked useWifPreview return the state under test.
+    const SAMPLE_WIF = "cVHcfvcWNc7DvqaPCwM6Z3DqZ";
+
+    function renderWithSecret(state: {
+      status: string;
+      identityId?: string;
+      dpnsName?: string | null;
+      purposeName?: string;
+      securityLevelName?: string;
+    }) {
+      mockUseSession.mockReturnValue(makeSession());
+      mockUseWifPreview.mockReturnValue(state);
+      const view = render(<LoginModal open onClose={vi.fn()} />);
+      fireEvent.change(view.getByPlaceholderText(/mnemonic phrase/i), {
+        target: { value: SAMPLE_WIF },
+      });
+      return view;
+    }
+
+    it("hides the preview region when state is idle", () => {
+      renderWithSecret({ status: "idle" });
+      expect(screen.queryByTestId("wif-preview")).toBeNull();
+    });
+
+    it("shows 'Checking…' while resolving", () => {
+      renderWithSecret({ status: "checking" });
+      expect(screen.getByTestId("wif-preview").textContent).toMatch(
+        /checking/i,
+      );
+    });
+
+    it("prefers DPNS name over truncated ID on the resolved state", () => {
+      renderWithSecret({
+        status: "resolved",
+        identityId: "abcdef0123456789xyz",
+        dpnsName: "alice",
+      });
+      const text = screen.getByTestId("wif-preview").textContent ?? "";
+      expect(text).toContain("alice.dash");
+      expect(text).not.toContain("abcdef01");
+    });
+
+    it("falls back to a truncated identity ID when DPNS name is null", () => {
+      renderWithSecret({
+        status: "resolved",
+        identityId: "abcdefghijklmnopqrstuvwx",
+        dpnsName: null,
+      });
+      const text = screen.getByTestId("wif-preview").textContent ?? "";
+      // First 8 chars + last 4 chars, with an ellipsis in between.
+      expect(text).toContain("abcdefgh");
+      expect(text).toContain("uvwx");
+    });
+
+    it("labels MASTER auth keys distinctly from purpose mismatches", () => {
+      renderWithSecret({
+        status: "wrong-purpose",
+        identityId: "id-master",
+        dpnsName: null,
+        purposeName: "AUTHENTICATION",
+        securityLevelName: "MASTER",
+      });
+      const text = screen.getByTestId("wif-preview").textContent ?? "";
+      expect(text).toMatch(/MASTER authentication/);
+      // Must not call it just "AUTHENTICATION key" — that would be confusing
+      // (every auth key is an "authentication" key).
+      expect(text).not.toMatch(/this is a AUTHENTICATION key/);
+    });
+
+    it("uses purposeName directly for non-AUTHENTICATION purposes", () => {
+      renderWithSecret({
+        status: "wrong-purpose",
+        identityId: "id-transfer",
+        dpnsName: null,
+        purposeName: "TRANSFER",
+        // Using a level name that does NOT appear in the static suffix
+        // ("HIGH or CRITICAL authentication key instead") so we can verify
+        // the conditional doesn't insert it for non-AUTHENTICATION purposes.
+        securityLevelName: "MEDIUM",
+      });
+      const text = screen.getByTestId("wif-preview").textContent ?? "";
+      expect(text).toMatch(/this is a TRANSFER key/);
+      // securityLevelName is only relevant for AUTHENTICATION + non-HIGH/CRITICAL;
+      // for TRANSFER it must not appear.
+      expect(text).not.toContain("MEDIUM");
+    });
+
+    it("disables the Login button when preview is wrong-purpose", () => {
+      renderWithSecret({
+        status: "wrong-purpose",
+        identityId: "id-x",
+        dpnsName: null,
+        purposeName: "TRANSFER",
+        securityLevelName: "CRITICAL",
+      });
+      const button = screen.getByRole("button", {
+        name: /^login$/i,
+      }) as HTMLButtonElement;
+      expect(button.disabled).toBe(true);
+    });
+
+    it("disables the Login button when preview is key-disabled", () => {
+      renderWithSecret({
+        status: "key-disabled",
+        identityId: "id-y",
+        dpnsName: null,
+      });
+      const button = screen.getByRole("button", {
+        name: /^login$/i,
+      }) as HTMLButtonElement;
+      expect(button.disabled).toBe(true);
+    });
+
+    it("leaves the Login button enabled while preview is checking", () => {
+      // We don't want to block submission on a debounce — the user should
+      // be able to hit Enter immediately after pasting.
+      renderWithSecret({ status: "checking" });
+      const button = screen.getByRole("button", {
+        name: /^login$/i,
+      }) as HTMLButtonElement;
+      expect(button.disabled).toBe(false);
+    });
+
+    it("does not render the preview when input looks like a mnemonic", () => {
+      mockUseSession.mockReturnValue(makeSession());
+      // Even if the hook were to return a non-idle state, the gate in
+      // LoginModal hides the preview region for mnemonic-shaped input.
+      mockUseWifPreview.mockReturnValue({ status: "checking" });
+      render(<LoginModal open onClose={vi.fn()} />);
+      fireEvent.change(screen.getByPlaceholderText(/mnemonic phrase/i), {
+        target: { value: "two words here" },
+      });
+      expect(screen.queryByTestId("wif-preview")).toBeNull();
+    });
+  });
 });
diff --git a/example-apps/dashnote/test/SessionContext.test.tsx b/example-apps/dashnote/test/SessionContext.test.tsx
index 48ba06a..cf7e46d 100644
--- a/example-apps/dashnote/test/SessionContext.test.tsx
+++ b/example-apps/dashnote/test/SessionContext.test.tsx
@@ -10,6 +10,7 @@ const {
   mockRefreshContractCache,
   mockDpnsUsername,
   mockResolveDpnsName,
+  mockLoginWithPrivateKey,
   mockToastError,
   mockToastSuccess,
 } = vi.hoisted(() => ({
@@ -18,6 +19,7 @@ const {
   mockRefreshContractCache: vi.fn(),
   mockDpnsUsername: vi.fn(),
   mockResolveDpnsName: vi.fn(),
+  mockLoginWithPrivateKey: vi.fn(),
   mockToastError: vi.fn(),
   mockToastSuccess: vi.fn(),
 }));
@@ -29,6 +31,14 @@ vi.mock("../../../setupDashClient-core.mjs", () => ({
   },
 }));
 
+vi.mock("../src/dash/loginWithPrivateKey", () => ({
+  loginWithPrivateKey: mockLoginWithPrivateKey,
+  UnknownIdentityError: class UnknownIdentityError extends Error {},
+  WrongKeyPurposeError: class WrongKeyPurposeError extends Error {},
+  KeyDisabledError: class KeyDisabledError extends Error {},
+  InvalidPrivateKeyError: class InvalidPrivateKeyError extends Error {},
+}));
+
 // Default resolver delegates to the real implementation (which calls
 // sdk.dpns.username — already mocked via mockDpnsUsername). Specific tests
 // override this to make resolveDpnsName itself throw, exercising the outer
@@ -99,6 +109,7 @@ beforeEach(() => {
   mockToastError.mockReset();
   mockToastSuccess.mockReset();
   mockResolveDpnsName.mockReset();
+  mockLoginWithPrivateKey.mockReset();
   mockResolveDpnsName.mockImplementation(async (sdk, identityId) => {
     const result = await sdk.dpns.username(identityId);
     if (typeof result !== "string" || result.length === 0) return null;
@@ -362,7 +373,7 @@ describe("SessionProvider", () => {
     const ref = mountSession();
 
     await act(async () => {
-      await ref.current.login("mnemonic", { rememberMe: true });
+      await ref.current.login("test mnemonic", { rememberMe: true });
     });
     expect(ref.current.status).toBe("authenticated");
 
@@ -419,7 +430,7 @@ describe("SessionProvider", () => {
     const ref = mountSession();
 
     await act(async () => {
-      await ref.current.login("mnemonic");
+      await ref.current.login("test mnemonic");
     });
 
     act(() => {
@@ -438,7 +449,7 @@ describe("SessionProvider", () => {
     const ref = mountSession();
 
     await act(async () => {
-      await ref.current.login("mnemonic");
+      await ref.current.login("test mnemonic");
     });
     expect(ref.current.dpnsName).toBe("alice");
 
@@ -472,7 +483,7 @@ describe("SessionProvider", () => {
     const ref = mountSession();
 
     await act(async () => {
-      await ref.current.login("mnemonic");
+      await ref.current.login("test mnemonic");
     });
     expect(ref.current.dpnsName).toBe("alice");
 
@@ -484,4 +495,156 @@ describe("SessionProvider", () => {
     expect(ref.current.identityId).toBeNull();
     expect(ref.current.status).toBe("readonly");
   });
+
+  it("dispatches a WIF input to loginWithPrivateKey, not IdentityKeyManager", async () => {
+    mockLoginWithPrivateKey.mockResolvedValue({
+      identityId: "wif-identity-id",
+      identity: { id: "wif-identity-id" },
+      identityKey: { mock: "key" },
+      signer: { mock: "signer" },
+    });
+    const ref = mountSession();
+
+    await act(async () => {
+      await ref.current.login("cVHcfvcWNc7DvqaPCwM6Z3", { rememberMe: true });
+    });
+
+    expect(mockLoginWithPrivateKey).toHaveBeenCalledTimes(1);
+    expect(mockKeyManagerCreate).not.toHaveBeenCalled();
+    expect(ref.current.status).toBe("authenticated");
+    expect(ref.current.identityId).toBe("wif-identity-id");
+    expect(ref.current.keyManager?.identityId).toBe("wif-identity-id");
+  });
+
+  it("failed WIF login from idle returns to idle without clobbering identity state", async () => {
+    mockLoginWithPrivateKey.mockRejectedValue(
+      new Error("Found identity X, but this is a transfer key."),
+    );
+    const ref = mountSession();
+    expect(ref.current.status).toBe("idle");
+
+    await act(async () => {
+      await ref.current.login("cVHcfvcWNc7DvqaPCwM6Z3").catch(() => undefined);
+    });
+
+    expect(ref.current.status).toBe("idle");
+    expect(ref.current.keyManager).toBeNull();
+    expect(ref.current.identityId).toBeNull();
+    expect(ref.current.error).toMatch(/transfer key/);
+    // Assert the precise message reaches the toast — guards against a
+    // future refactor swallowing it into a generic "Login failed".
+    expect(mockToastError).toHaveBeenCalledWith(
+      expect.stringContaining("transfer key"),
+    );
+  });
+
+  it("failed login from authenticated without rememberMe restores authenticated state", async () => {
+    // Locks in the snapshot/restore branch for the case where no
+    // remembered identity exists. Without the snapshot/restore, a failed
+    // key-swap from an authenticated session would log the user out.
+    mockKeyManagerCreate.mockResolvedValueOnce({
+      identityId: "logged-in-id",
+    });
+    const ref = mountSession();
+    await act(async () => {
+      await ref.current.login("test mnemonic", { rememberMe: false });
+    });
+    expect(ref.current.status).toBe("authenticated");
+    const priorKeyManager = ref.current.keyManager;
+    expect(priorKeyManager).not.toBeNull();
+    expect(ref.current.rememberedIdentityId).toBeNull();
+
+    mockLoginWithPrivateKey.mockRejectedValueOnce(
+      new Error("Found identity Y, but this is a transfer key."),
+    );
+    await act(async () => {
+      await ref.current.login("cVHcfvcWNc7DvqaPCwM6Z3").catch(() => undefined);
+    });
+
+    expect(ref.current.status).toBe("authenticated");
+    expect(ref.current.identityId).toBe("logged-in-id");
+    expect(ref.current.keyManager).toBe(priorKeyManager);
+    expect(ref.current.rememberedIdentityId).toBeNull();
+    expect(ref.current.error).toMatch(/transfer key/);
+  });
+
+  it("failed WIF login from browsing keeps the remembered identity panel intact", async () => {
+    // Reproduces the screenshot bug: a wrong-purpose key while browsing
+    // a remembered identity should NOT log the user out.
+    localStorage.setItem(
+      REMEMBERED_KEY,
+      JSON.stringify({ id: "remembered-id", name: "alice" }),
+    );
+    mockLoginWithPrivateKey.mockRejectedValue(
+      new Error("Found identity X, but this is a transfer key."),
+    );
+    const ref = mountSession();
+    expect(ref.current.status).toBe("browsing");
+
+    await act(async () => {
+      await ref.current.login("cVHcfvcWNc7DvqaPCwM6Z3").catch(() => undefined);
+    });
+
+    expect(ref.current.status).toBe("browsing");
+    expect(ref.current.identityId).toBe("remembered-id");
+    expect(ref.current.dpnsName).toBe("alice");
+    expect(ref.current.rememberedIdentityId).toBe("remembered-id");
+    expect(ref.current.keyManager).toBeNull();
+    expect(ref.current.error).toMatch(/transfer key/);
+    expect(mockToastError).toHaveBeenCalledWith(
+      expect.stringContaining("transfer key"),
+    );
+  });
+
+  it("failed switch-identity from authenticated keeps the active session", async () => {
+    // First, authenticate so a real keyManager + remembered identity exist.
+    mockKeyManagerCreate.mockResolvedValueOnce({
+      identityId: "logged-in-id",
+    });
+    const ref = mountSession();
+    await act(async () => {
+      await ref.current.login("test mnemonic", { rememberMe: true });
+    });
+    expect(ref.current.status).toBe("authenticated");
+    const priorKeyManager = ref.current.keyManager;
+    expect(priorKeyManager).not.toBeNull();
+
+    // Now attempt to switch with a wrong-purpose WIF. The active session
+    // must NOT drop — typing a bad secret while signed in should never log
+    // the user out, even if a remembered identity is present in storage.
+    mockLoginWithPrivateKey.mockRejectedValueOnce(
+      new Error("Found identity Y, but this is a transfer key."),
+    );
+    await act(async () => {
+      await ref.current.login("cVHcfvcWNc7DvqaPCwM6Z3").catch(() => undefined);
+    });
+
+    expect(ref.current.status).toBe("authenticated");
+    expect(ref.current.identityId).toBe("logged-in-id");
+    expect(ref.current.keyManager).toBe(priorKeyManager);
+    expect(ref.current.error).toMatch(/transfer key/);
+    expect(mockToastError).toHaveBeenCalledWith(
+      expect.stringContaining("transfer key"),
+    );
+  });
+
+  it("failed mnemonic login from idle restores idle state (not just the WIF path)", async () => {
+    mockKeyManagerCreate.mockRejectedValue(new Error("Bad mnemonic checksum."));
+    const ref = mountSession();
+    expect(ref.current.status).toBe("idle");
+
+    await act(async () => {
+      await ref.current
+        .login("not a real mnemonic phrase")
+        .catch(() => undefined);
+    });
+
+    expect(ref.current.status).toBe("idle");
+    expect(ref.current.keyManager).toBeNull();
+    expect(ref.current.identityId).toBeNull();
+    expect(ref.current.error).toMatch(/checksum/);
+    expect(mockToastError).toHaveBeenCalledWith(
+      expect.stringContaining("checksum"),
+    );
+  });
 });
diff --git a/example-apps/dashnote/test/detectSecretShape.test.ts b/example-apps/dashnote/test/detectSecretShape.test.ts
new file mode 100644
index 0000000..5c1107b
--- /dev/null
+++ b/example-apps/dashnote/test/detectSecretShape.test.ts
@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+
+import { detectSecretShape, looksLikeWif } from "../src/lib/detectSecretShape";
+
+describe("detectSecretShape", () => {
+  it("returns mnemonic for a 12-word phrase", () => {
+    expect(
+      detectSecretShape(
+        "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+      ),
+    ).toBe("mnemonic");
+  });
+
+  it("returns mnemonic for a 24-word phrase", () => {
+    const phrase = Array(24).fill("word").join(" ");
+    expect(detectSecretShape(phrase)).toBe("mnemonic");
+  });
+
+  it("returns wif for a base58 string with no whitespace", () => {
+    expect(
+      detectSecretShape("cVHcfvcWNc7DvqaPCwM6Z3DqZqZqZqZqZqZqZqZqZqZqZqZqZqZq"),
+    ).toBe("wif");
+  });
+
+  it("returns wif for hex (no whitespace) — parser will reject downstream", () => {
+    expect(
+      detectSecretShape(
+        "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+      ),
+    ).toBe("wif");
+  });
+
+  it("returns wif for empty input — parser will reject downstream", () => {
+    expect(detectSecretShape("")).toBe("wif");
+  });
+
+  it("returns wif for a single word — parser will reject downstream", () => {
+    expect(detectSecretShape("abandon")).toBe("wif");
+  });
+
+  it("treats leading/trailing whitespace around a WIF as wif (after trim)", () => {
+    expect(detectSecretShape("   cVHcfvcWNc7DvqaPCwM6Z3DqZ   ")).toBe("wif");
+  });
+
+  it("returns mnemonic when interior whitespace is present even with stray text", () => {
+    expect(detectSecretShape("note: abandon abandon")).toBe("mnemonic");
+  });
+});
+
+describe("looksLikeWif", () => {
+  // Real-shape testnet WIFs: 52-char compressed and 51-char uncompressed.
+  const compressed = "cVHcfvcWNc7DvqaPCwM6Z3DqZQqZqZqZqZqZqZqZqZqZqZqZqZqZ";
+  const uncompressed = "9JbT9rkLcXzVqUsMNvFvHJtKdwYZHGfRbScVTpQrLnBxAyEoMmL";
+
+  it("accepts 52-char base58 input (compressed WIF length)", () => {
+    expect(compressed).toHaveLength(52);
+    expect(looksLikeWif(compressed)).toBe(true);
+  });
+
+  it("accepts 51-char base58 input (uncompressed WIF length)", () => {
+    expect(uncompressed).toHaveLength(51);
+    expect(looksLikeWif(uncompressed)).toBe(true);
+  });
+
+  it("rejects input shorter than 51 chars (still typing)", () => {
+    expect(looksLikeWif("cVHcfvcWNc7Dvqa")).toBe(false);
+    expect(looksLikeWif("")).toBe(false);
+  });
+
+  it("rejects input longer than 52 chars", () => {
+    expect(looksLikeWif(`${compressed}X`)).toBe(false);
+  });
+
+  it("rejects input containing characters outside the base58 alphabet", () => {
+    // 0, O, I, l are excluded from base58.
+    const withZero = `0${compressed.slice(1)}`;
+    const withCapitalO = `O${compressed.slice(1)}`;
+    const withCapitalI = `I${compressed.slice(1)}`;
+    const withLowercaseL = `l${compressed.slice(1)}`;
+    expect(looksLikeWif(withZero)).toBe(false);
+    expect(looksLikeWif(withCapitalO)).toBe(false);
+    expect(looksLikeWif(withCapitalI)).toBe(false);
+    expect(looksLikeWif(withLowercaseL)).toBe(false);
+  });
+
+  it("rejects hex containing '0' (excluded from base58)", () => {
+    const hexWithZero = "0".repeat(52);
+    expect(looksLikeWif(hexWithZero)).toBe(false);
+  });
+
+  it("ACCEPTS 52-char hex without '0' — gate is structural, not semantic", () => {
+    // Documents intentional behavior: hex 1-9 + a-f is a subset of base58, so
+    // a 52-char hex string of those characters passes the structural gate.
+    // The downstream PrivateKey.fromWIF parser is responsible for catching
+    // it (bad checksum / version byte). The eager-preview UI must not error
+    // on this — it falls into the silent "idle" branch via UnknownIdentity
+    // or a generic parse rejection.
+    // 52 chars of hex digits, all of which are also valid base58 (1-9 a-f).
+    const hexNoZero = "abcdef123456789".repeat(4).slice(0, 52);
+    expect(hexNoZero).toHaveLength(52);
+    expect(looksLikeWif(hexNoZero)).toBe(true);
+  });
+
+  it("trims whitespace before measuring length", () => {
+    expect(looksLikeWif(`  ${compressed}  `)).toBe(true);
+  });
+
+  it("rejects mnemonic-shaped input (whitespace breaks length+charset)", () => {
+    expect(
+      looksLikeWif(
+        "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+      ),
+    ).toBe(false);
+  });
+});
diff --git a/example-apps/dashnote/test/loginWithPrivateKey.test.ts b/example-apps/dashnote/test/loginWithPrivateKey.test.ts
new file mode 100644
index 0000000..a4d2e23
--- /dev/null
+++ b/example-apps/dashnote/test/loginWithPrivateKey.test.ts
@@ -0,0 +1,447 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { mockFromWIF, mockGetPublicKeyHash, mockSignerAddKeyFromWif } =
+  vi.hoisted(() => ({
+    mockFromWIF: vi.fn(),
+    mockGetPublicKeyHash: vi.fn(),
+    mockSignerAddKeyFromWif: vi.fn(),
+  }));
+
+vi.mock("@dashevo/evo-sdk", () => ({
+  PrivateKey: { fromWIF: mockFromWIF },
+  IdentitySigner: function MockSigner() {
+    return { addKeyFromWif: mockSignerAddKeyFromWif };
+  },
+  Purpose: {
+    AUTHENTICATION: 0,
+    ENCRYPTION: 1,
+    TRANSFER: 2,
+  },
+  SecurityLevel: {
+    MASTER: 0,
+    CRITICAL: 1,
+    HIGH: 2,
+    MEDIUM: 3,
+  },
+}));
+
+import {
+  KeyDisabledError,
+  InvalidPrivateKeyError,
+  loginWithPrivateKey,
+  resolveIdentityFromWif,
+  UnknownIdentityError,
+  WrongKeyPurposeError,
+} from "../src/dash/loginWithPrivateKey";
+import type { DashSdk } from "../src/dash/types";
+
+const ourPubKeyHex =
+  "02aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899";
+const ourPubKeyBytes = (() => {
+  const bytes = new Uint8Array(ourPubKeyHex.length / 2);
+  for (let i = 0; i < bytes.length; i += 1) {
+    bytes[i] = parseInt(ourPubKeyHex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+})();
+const ourPubKeyBase64 = (() => {
+  let binary = "";
+  ourPubKeyBytes.forEach((b) => {
+    binary += String.fromCharCode(b);
+  });
+  return btoa(binary);
+})();
+
+function setupValidWifMocks() {
+  mockGetPublicKeyHash.mockReturnValue(new Uint8Array(20));
+  mockFromWIF.mockReturnValue({
+    getPublicKeyHash: mockGetPublicKeyHash,
+    getPublicKey: () => ({
+      toBytes: () => ourPubKeyBytes,
+    }),
+  });
+}
+
+function makeSdk(byPublicKeyHash: ReturnType<typeof vi.fn>): DashSdk {
+  return {
+    identities: {
+      byPublicKeyHash,
+      nonce: vi.fn(),
+    },
+  } as unknown as DashSdk;
+}
+
+afterEach(() => {
+  mockFromWIF.mockReset();
+  mockGetPublicKeyHash.mockReset();
+  mockSignerAddKeyFromWif.mockReset();
+});
+
+describe("loginWithPrivateKey", () => {
+  it("throws InvalidPrivateKeyError when the WIF can't be parsed", async () => {
+    mockFromWIF.mockImplementation(() => {
+      throw new Error("bad checksum");
+    });
+    const sdk = makeSdk(vi.fn());
+
+    await expect(loginWithPrivateKey(sdk, "not-a-key")).rejects.toBeInstanceOf(
+      InvalidPrivateKeyError,
+    );
+  });
+
+  it("throws UnknownIdentityError when no identity matches the key", async () => {
+    setupValidWifMocks();
+    const byPublicKeyHash = vi.fn().mockResolvedValue(undefined);
+    const sdk = makeSdk(byPublicKeyHash);
+
+    await expect(
+      loginWithPrivateKey(sdk, "valid-wif-stub"),
+    ).rejects.toBeInstanceOf(UnknownIdentityError);
+  });
+
+  it("throws WrongKeyPurposeError carrying the identity ID for transfer keys", async () => {
+    setupValidWifMocks();
+    const identityId = "identity-1";
+    const identity = {
+      id: identityId,
+      toJSON: () => ({
+        publicKeys: [
+          {
+            id: 3,
+            purpose: 2, // TRANSFER
+            securityLevel: 1, // CRITICAL
+            data: ourPubKeyBase64,
+          },
+        ],
+      }),
+      getPublicKeyById: vi.fn(),
+    };
+    const sdk = makeSdk(vi.fn().mockResolvedValue(identity));
+
+    const promise = loginWithPrivateKey(sdk, "valid-wif-stub");
+    await expect(promise).rejects.toBeInstanceOf(WrongKeyPurposeError);
+    await promise.catch((err: WrongKeyPurposeError) => {
+      expect(err.identityId).toBe(identityId);
+      expect(err.purposeName).toBe("TRANSFER");
+      expect(err.securityLevelName).toBe("CRITICAL");
+    });
+  });
+
+  it("labels MASTER auth keys with securityLevelName=MASTER on the error", async () => {
+    // Eager preview UI uses securityLevelName to differentiate "AUTHENTICATION
+    // + MASTER" (MASTER auth key) from "TRANSFER" / "ENCRYPTION" purposes —
+    // both throw WrongKeyPurposeError but read very differently to the user.
+    setupValidWifMocks();
+    const identity = {
+      id: "identity-master",
+      toJSON: () => ({
+        publicKeys: [
+          {
+            id: 0,
+            purpose: 0, // AUTHENTICATION
+            securityLevel: 0, // MASTER
+            data: ourPubKeyBase64,
+          },
+        ],
+      }),
+      getPublicKeyById: vi.fn(),
+    };
+    const sdk = makeSdk(vi.fn().mockResolvedValue(identity));
+
+    const promise = loginWithPrivateKey(sdk, "valid-wif-stub");
+    await expect(promise).rejects.toBeInstanceOf(WrongKeyPurposeError);
+    await promise.catch((err: WrongKeyPurposeError) => {
+      expect(err.purposeName).toBe("AUTHENTICATION");
+      expect(err.securityLevelName).toBe("MASTER");
+    });
+  });
+
+  it("throws KeyDisabledError when the matching key has a disabledAt timestamp", async () => {
+    setupValidWifMocks();
+    const identityId = "identity-2";
+    const identity = {
+      id: identityId,
+      toJSON: () => ({
+        publicKeys: [
+          {
+            id: 1,
+            purpose: 0, // AUTHENTICATION
+            securityLevel: 2, // HIGH
+            data: ourPubKeyBase64,
+            disabledAt: 1700000000,
+          },
+        ],
+      }),
+      getPublicKeyById: vi.fn(),
+    };
+    const sdk = makeSdk(vi.fn().mockResolvedValue(identity));
+
+    const promise = loginWithPrivateKey(sdk, "valid-wif-stub");
+    await expect(promise).rejects.toBeInstanceOf(KeyDisabledError);
+    await promise.catch((err: KeyDisabledError) => {
+      expect(err.identityId).toBe(identityId);
+    });
+  });
+
+  it("throws KeyDisabledError when the matching key has disabled: true", async () => {
+    // Some SDK versions surface the disabled state as a boolean rather than
+    // a timestamp. The check must catch both shapes.
+    setupValidWifMocks();
+    const identityId = "identity-disabled-bool";
+    const identity = {
+      id: identityId,
+      toJSON: () => ({
+        publicKeys: [
+          {
+            id: 1,
+            purpose: 0,
+            securityLevel: 2,
+            data: ourPubKeyBase64,
+            disabled: true,
+          },
+        ],
+      }),
+      getPublicKeyById: vi.fn(),
+    };
+    const sdk = makeSdk(vi.fn().mockResolvedValue(identity));
+
+    const promise = loginWithPrivateKey(sdk, "valid-wif-stub");
+    await expect(promise).rejects.toBeInstanceOf(KeyDisabledError);
+    await promise.catch((err: KeyDisabledError) => {
+      expect(err.identityId).toBe(identityId);
+    });
+  });
+
+  it("throws UnknownIdentityError when the identity has an empty publicKeys array", async () => {
+    // Defensive: byPublicKeyHash matched, so a key must exist on the
+    // identity. An empty publicKeys[] indicates an SDK shape we don't
+    // understand; fail closed rather than guessing.
+    setupValidWifMocks();
+    const identity = {
+      id: "identity-no-keys",
+      toJSON: () => ({ publicKeys: [] }),
+      getPublicKeyById: vi.fn(),
+    };
+    const sdk = makeSdk(vi.fn().mockResolvedValue(identity));
+
+    await expect(
+      loginWithPrivateKey(sdk, "valid-wif-stub"),
+    ).rejects.toBeInstanceOf(UnknownIdentityError);
+  });
+
+  it("throws UnknownIdentityError when no publicKeys[].data matches our pubkey bytes", async () => {
+    // Defensive: byPublicKeyHash returned an identity, but the JSON
+    // encoding of its keys' data field is something we can't reconcile
+    // (different encoding, different pubkey shape). Fail closed instead
+    // of silently picking the first key.
+    setupValidWifMocks();
+    // Use a base64 string that contains characters outside [0-9a-fA-F] so
+    // tryDecodeKeyData skips its hex branch and exercises the base64 path
+    // we actually want to verify here. 33 bytes of 0xff base64-encodes
+    // with '/' and '=' — definitively not hex.
+    const otherKeyBase64 = btoa("\xff".repeat(33));
+    expect(otherKeyBase64).toMatch(/[^0-9a-fA-F]/);
+    const identity = {
+      id: "identity-encoding-skew",
+      toJSON: () => ({
+        publicKeys: [
+          {
+            id: 1,
+            purpose: 0,
+            securityLevel: 2,
+            data: otherKeyBase64,
+          },
+        ],
+      }),
+      getPublicKeyById: vi.fn(),
+    };
+    const sdk = makeSdk(vi.fn().mockResolvedValue(identity));
+
+    await expect(
+      loginWithPrivateKey(sdk, "valid-wif-stub"),
+    ).rejects.toBeInstanceOf(UnknownIdentityError);
+  });
+
+  it("returns the matched key + signer wired with the original WIF", async () => {
+    setupValidWifMocks();
+    const identityId = "identity-3";
+    const identityKey = { mock: "identity-public-key" };
+    const getPublicKeyById = vi.fn().mockReturnValue(identityKey);
+    const identity = {
+      id: identityId,
+      toJSON: () => ({
+        publicKeys: [
+          {
+            id: 2,
+            purpose: 0, // AUTHENTICATION
+            securityLevel: 1, // CRITICAL
+            data: ourPubKeyBase64,
+          },
+        ],
+      }),
+      getPublicKeyById,
+    };
+    const sdk = makeSdk(vi.fn().mockResolvedValue(identity));
+
+    const result = await loginWithPrivateKey(sdk, "valid-wif-stub");
+
+    expect(result.identityId).toBe(identityId);
+    expect(result.identity).toBe(identity);
+    expect(result.identityKey).toBe(identityKey);
+    expect(getPublicKeyById).toHaveBeenCalledWith(2);
+    expect(mockSignerAddKeyFromWif).toHaveBeenCalledWith("valid-wif-stub");
+  });
+
+  it("matches keys whose JSON data is hex-encoded", async () => {
+    setupValidWifMocks();
+    const identity = {
+      id: "identity-hex",
+      toJSON: () => ({
+        publicKeys: [
+          {
+            id: 1,
+            purpose: 0,
+            securityLevel: 2, // HIGH
+            data: ourPubKeyHex,
+          },
+        ],
+      }),
+      getPublicKeyById: vi.fn().mockReturnValue({}),
+    };
+    const sdk = makeSdk(vi.fn().mockResolvedValue(identity));
+
+    const result = await loginWithPrivateKey(sdk, "valid-wif-stub");
+    expect(result.identityId).toBe("identity-hex");
+  });
+
+  describe("resolveIdentityFromWif", () => {
+    // The eager preview path uses resolveIdentityFromWif so it can validate
+    // the WIF + key purpose without touching the WASM signer. The contract:
+    // same checks, same errors, no signer side effects.
+    it("returns identity + matched key without invoking the signer", async () => {
+      setupValidWifMocks();
+      const identityKey = { mock: "identity-public-key" };
+      const getPublicKeyById = vi.fn().mockReturnValue(identityKey);
+      const identity = {
+        id: "identity-resolve",
+        toJSON: () => ({
+          publicKeys: [
+            {
+              id: 1,
+              purpose: 0, // AUTHENTICATION
+              securityLevel: 2, // HIGH
+              data: ourPubKeyBase64,
+            },
+          ],
+        }),
+        getPublicKeyById,
+      };
+      const sdk = makeSdk(vi.fn().mockResolvedValue(identity));
+
+      const result = await resolveIdentityFromWif(sdk, "valid-wif-stub");
+
+      expect(result.identityId).toBe("identity-resolve");
+      expect(result.identity).toBe(identity);
+      expect(result.identityKey).toBe(identityKey);
+      expect(result.matched.id).toBe(1);
+      // No signer construction in the preview path.
+      expect(mockSignerAddKeyFromWif).not.toHaveBeenCalled();
+    });
+
+    it("throws the same WrongKeyPurposeError as loginWithPrivateKey", async () => {
+      setupValidWifMocks();
+      const identity = {
+        id: "identity-resolve-wrong",
+        toJSON: () => ({
+          publicKeys: [
+            {
+              id: 1,
+              purpose: 2, // TRANSFER
+              securityLevel: 1,
+              data: ourPubKeyBase64,
+            },
+          ],
+        }),
+        getPublicKeyById: vi.fn(),
+      };
+      const sdk = makeSdk(vi.fn().mockResolvedValue(identity));
+
+      await expect(
+        resolveIdentityFromWif(sdk, "valid-wif-stub"),
+      ).rejects.toBeInstanceOf(WrongKeyPurposeError);
+      expect(mockSignerAddKeyFromWif).not.toHaveBeenCalled();
+    });
+
+    it("throws InvalidPrivateKeyError for unparseable WIFs", async () => {
+      mockFromWIF.mockImplementation(() => {
+        throw new Error("bad checksum");
+      });
+      const sdk = makeSdk(vi.fn());
+
+      await expect(
+        resolveIdentityFromWif(sdk, "not-a-key"),
+      ).rejects.toBeInstanceOf(InvalidPrivateKeyError);
+      expect(mockSignerAddKeyFromWif).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("security level gate", () => {
+    function makeIdentityWithKey(opts: { purpose: number; level: number }) {
+      return {
+        id: `identity-p${opts.purpose}-l${opts.level}`,
+        toJSON: () => ({
+          publicKeys: [
+            {
+              id: 1,
+              purpose: opts.purpose,
+              securityLevel: opts.level,
+              data: ourPubKeyBase64,
+            },
+          ],
+        }),
+        getPublicKeyById: vi.fn().mockReturnValue({}),
+      };
+    }
+
+    // SecurityLevel: MASTER=0, CRITICAL=1, HIGH=2, MEDIUM=3
+    // Purpose: AUTHENTICATION=0, ENCRYPTION=1, TRANSFER=2
+    // Document/contract operations require AUTHENTICATION + (HIGH | CRITICAL).
+    // Anything else must be rejected up front so we don't reach a
+    // "level ... is not a valid level for these state transitions" failure
+    // mid-flow.
+    it.each([
+      { purpose: 0, level: 0, name: "AUTHENTICATION + MASTER" },
+      { purpose: 0, level: 3, name: "AUTHENTICATION + MEDIUM" },
+      { purpose: 1, level: 0, name: "ENCRYPTION + MASTER" },
+      { purpose: 1, level: 1, name: "ENCRYPTION + CRITICAL" },
+      { purpose: 1, level: 2, name: "ENCRYPTION + HIGH" },
+      { purpose: 1, level: 3, name: "ENCRYPTION + MEDIUM" },
+      { purpose: 2, level: 0, name: "TRANSFER + MASTER" },
+      { purpose: 2, level: 1, name: "TRANSFER + CRITICAL" },
+      { purpose: 2, level: 2, name: "TRANSFER + HIGH" },
+      { purpose: 2, level: 3, name: "TRANSFER + MEDIUM" },
+    ])("rejects $name", async ({ purpose, level }) => {
+      setupValidWifMocks();
+      const identity = makeIdentityWithKey({ purpose, level });
+      const sdk = makeSdk(vi.fn().mockResolvedValue(identity));
+
+      await expect(
+        loginWithPrivateKey(sdk, "valid-wif-stub"),
+      ).rejects.toBeInstanceOf(WrongKeyPurposeError);
+    });
+
+    it.each([
+      { level: 1, name: "CRITICAL" },
+      { level: 2, name: "HIGH" },
+    ])("accepts AUTHENTICATION + $name", async ({ level }) => {
+      setupValidWifMocks();
+      const identity = makeIdentityWithKey({ purpose: 0, level });
+      const sdk = makeSdk(vi.fn().mockResolvedValue(identity));
+
+      const result = await loginWithPrivateKey(sdk, "valid-wif-stub");
+      expect(result.identityId).toBe(`identity-p0-l${level}`);
+    });
+  });
+});
diff --git a/example-apps/dashnote/test/useWifPreview.test.tsx b/example-apps/dashnote/test/useWifPreview.test.tsx
new file mode 100644
index 0000000..5e185de
--- /dev/null
+++ b/example-apps/dashnote/test/useWifPreview.test.tsx
@@ -0,0 +1,327 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, render } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  mockResolveIdentityFromWif,
+  mockResolveDpnsName,
+  WrongKeyPurposeError,
+  KeyDisabledError,
+  UnknownIdentityError,
+  InvalidPrivateKeyError,
+} = vi.hoisted(() => {
+  class WrongKeyPurposeError extends Error {
+    identityId: string;
+    purposeName: string;
+    securityLevelName: string;
+    constructor(
+      identityId: string,
+      purposeName: string,
+      securityLevelName: string,
+    ) {
+      super("wrong purpose");
+      this.identityId = identityId;
+      this.purposeName = purposeName;
+      this.securityLevelName = securityLevelName;
+    }
+  }
+  class KeyDisabledError extends Error {
+    identityId: string;
+    constructor(identityId: string) {
+      super("disabled");
+      this.identityId = identityId;
+    }
+  }
+  class UnknownIdentityError extends Error {}
+  class InvalidPrivateKeyError extends Error {}
+  return {
+    mockResolveIdentityFromWif: vi.fn(),
+    mockResolveDpnsName: vi.fn(),
+    WrongKeyPurposeError,
+    KeyDisabledError,
+    UnknownIdentityError,
+    InvalidPrivateKeyError,
+  };
+});
+
+vi.mock("../src/dash/loginWithPrivateKey", () => ({
+  resolveIdentityFromWif: mockResolveIdentityFromWif,
+  WrongKeyPurposeError,
+  KeyDisabledError,
+  UnknownIdentityError,
+  InvalidPrivateKeyError,
+}));
+
+vi.mock("../src/dash/resolveDpnsName", () => ({
+  resolveDpnsName: mockResolveDpnsName,
+}));
+
+import {
+  useWifPreview,
+  type WifPreviewState,
+} from "../src/hooks/useWifPreview";
+import type { DashSdk } from "../src/dash/types";
+
+// 52-char compressed-WIF-shaped string. Content is irrelevant — `looksLikeWif`
+// only checks length + base58 charset, and the resolver is mocked.
+const VALID_WIF = "cVHcfvcWNc7DvqaPCwM6Z3DqZQqZqZqZqZqZqZqZqZqZqZqZqZqZ";
+const VALID_WIF_2 = "cWxKJZQqZqZqZqZqZqZqZqZqZqZqZqZqZqZqZqZqZqZqZqZqZqZq";
+const sdk = { tag: "fake-sdk" } as unknown as DashSdk;
+
+function Harness({
+  secret,
+  enabled = true,
+  onState,
+  sdkOverride,
+}: {
+  secret: string;
+  enabled?: boolean;
+  onState: (state: WifPreviewState) => void;
+  sdkOverride?: DashSdk | null;
+}) {
+  const state = useWifPreview(
+    sdkOverride === undefined ? sdk : sdkOverride,
+    secret,
+    enabled,
+  );
+  onState(state);
+  return null;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  mockResolveIdentityFromWif.mockReset();
+  mockResolveDpnsName.mockReset();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  cleanup();
+});
+
+async function flushDebounce() {
+  // Advance past the 400ms debounce, then yield once for the inner async
+  // resolver to settle.
+  await act(async () => {
+    vi.advanceTimersByTime(450);
+  });
+  await act(async () => {
+    await Promise.resolve();
+    await Promise.resolve();
+  });
+}
+
+describe("useWifPreview", () => {
+  it("returns idle when disabled, even for a valid-shaped WIF", async () => {
+    const states: WifPreviewState[] = [];
+    render(
+      <Harness
+        secret={VALID_WIF}
+        enabled={false}
+        onState={(s) => states.push(s)}
+      />,
+    );
+    await flushDebounce();
+    expect(states.every((s) => s.status === "idle")).toBe(true);
+    expect(mockResolveIdentityFromWif).not.toHaveBeenCalled();
+  });
+
+  it("returns idle for input that fails the structural gate (too short)", async () => {
+    const states: WifPreviewState[] = [];
+    render(<Harness secret="cVHcfvcWNc7" onState={(s) => states.push(s)} />);
+    await flushDebounce();
+    expect(states.every((s) => s.status === "idle")).toBe(true);
+    expect(mockResolveIdentityFromWif).not.toHaveBeenCalled();
+  });
+
+  it("returns idle when the SDK is null", async () => {
+    const states: WifPreviewState[] = [];
+    render(
+      <Harness
+        secret={VALID_WIF}
+        sdkOverride={null}
+        onState={(s) => states.push(s)}
+      />,
+    );
+    await flushDebounce();
+    expect(states.every((s) => s.status === "idle")).toBe(true);
+    expect(mockResolveIdentityFromWif).not.toHaveBeenCalled();
+  });
+
+  it("resolves to identity + DPNS name after the debounce", async () => {
+    mockResolveIdentityFromWif.mockResolvedValue({
+      identityId: "id-A",
+      identity: {},
+      matched: { id: 1, purpose: 0, securityLevel: 2 },
+      identityKey: {},
+    });
+    mockResolveDpnsName.mockResolvedValue("alice");
+
+    const states: WifPreviewState[] = [];
+    render(<Harness secret={VALID_WIF} onState={(s) => states.push(s)} />);
+
+    // Before the debounce fires the hook should report "checking" once it
+    // notices the gate is open.
+    expect(states.at(-1)?.status).toBe("checking");
+    expect(mockResolveIdentityFromWif).not.toHaveBeenCalled();
+
+    await flushDebounce();
+
+    expect(mockResolveIdentityFromWif).toHaveBeenCalledTimes(1);
+    expect(mockResolveDpnsName).toHaveBeenCalledWith(sdk, "id-A");
+    expect(states.at(-1)).toEqual({
+      status: "resolved",
+      identityId: "id-A",
+      dpnsName: "alice",
+    });
+  });
+
+  it("surfaces wrong-purpose with security level + DPNS name", async () => {
+    mockResolveIdentityFromWif.mockRejectedValue(
+      new WrongKeyPurposeError("id-B", "AUTHENTICATION", "MASTER"),
+    );
+    mockResolveDpnsName.mockResolvedValue("bob");
+
+    const states: WifPreviewState[] = [];
+    render(<Harness secret={VALID_WIF} onState={(s) => states.push(s)} />);
+    await flushDebounce();
+
+    expect(states.at(-1)).toEqual({
+      status: "wrong-purpose",
+      identityId: "id-B",
+      dpnsName: "bob",
+      purposeName: "AUTHENTICATION",
+      securityLevelName: "MASTER",
+    });
+  });
+
+  it("surfaces key-disabled with DPNS name", async () => {
+    mockResolveIdentityFromWif.mockRejectedValue(new KeyDisabledError("id-C"));
+    mockResolveDpnsName.mockResolvedValue(null);
+
+    const states: WifPreviewState[] = [];
+    render(<Harness secret={VALID_WIF} onState={(s) => states.push(s)} />);
+    await flushDebounce();
+
+    expect(states.at(-1)).toEqual({
+      status: "key-disabled",
+      identityId: "id-C",
+      dpnsName: null,
+    });
+  });
+
+  it("stays silent (idle) for UnknownIdentityError — no pre-submit error UI", async () => {
+    mockResolveIdentityFromWif.mockRejectedValue(new UnknownIdentityError());
+
+    const states: WifPreviewState[] = [];
+    render(<Harness secret={VALID_WIF} onState={(s) => states.push(s)} />);
+    await flushDebounce();
+
+    expect(states.at(-1)?.status).toBe("idle");
+    expect(mockResolveDpnsName).not.toHaveBeenCalled();
+  });
+
+  it("stays silent for unexpected errors (network blips, etc.)", async () => {
+    mockResolveIdentityFromWif.mockRejectedValue(new Error("network down"));
+
+    const states: WifPreviewState[] = [];
+    render(<Harness secret={VALID_WIF} onState={(s) => states.push(s)} />);
+    await flushDebounce();
+
+    expect(states.at(-1)?.status).toBe("idle");
+  });
+
+  it("does not call resolve when the WIF changes within the debounce window", async () => {
+    mockResolveIdentityFromWif.mockResolvedValue({
+      identityId: "id-D",
+      identity: {},
+      matched: { id: 1, purpose: 0, securityLevel: 2 },
+      identityKey: {},
+    });
+    mockResolveDpnsName.mockResolvedValue(null);
+
+    let secret = VALID_WIF;
+    const states: WifPreviewState[] = [];
+    const { rerender } = render(
+      <Harness secret={secret} onState={(s) => states.push(s)} />,
+    );
+
+    // Halfway through the debounce window, swap to a different WIF.
+    await act(async () => {
+      vi.advanceTimersByTime(200);
+    });
+    secret = VALID_WIF_2;
+    rerender(<Harness secret={secret} onState={(s) => states.push(s)} />);
+
+    // Now flush. Only the second WIF should produce a network call.
+    await flushDebounce();
+
+    expect(mockResolveIdentityFromWif).toHaveBeenCalledTimes(1);
+    expect(states.at(-1)?.status).toBe("resolved");
+  });
+
+  it("does not retain results across remount — secret state is component-local", async () => {
+    // The hook intentionally does not cache resolved outcomes across mounts;
+    // every fresh mount that re-passes the WIF performs the network call
+    // again. This bounds raw-WIF retention to the form's lifetime.
+    mockResolveIdentityFromWif.mockResolvedValue({
+      identityId: "id-fresh",
+      identity: {},
+      matched: { id: 1, purpose: 0, securityLevel: 2 },
+      identityKey: {},
+    });
+    mockResolveDpnsName.mockResolvedValue(null);
+
+    const { unmount } = render(
+      <Harness secret={VALID_WIF} onState={() => {}} />,
+    );
+    await flushDebounce();
+    expect(mockResolveIdentityFromWif).toHaveBeenCalledTimes(1);
+    unmount();
+
+    render(<Harness secret={VALID_WIF} onState={() => {}} />);
+    await flushDebounce();
+    expect(mockResolveIdentityFromWif).toHaveBeenCalledTimes(2);
+  });
+
+  it("trims whitespace before gating; passes the trimmed WIF to the resolver", async () => {
+    mockResolveIdentityFromWif.mockResolvedValue({
+      identityId: "id-trim",
+      identity: {},
+      matched: { id: 1, purpose: 0, securityLevel: 2 },
+      identityKey: {},
+    });
+    mockResolveDpnsName.mockResolvedValue(null);
+
+    const states: WifPreviewState[] = [];
+    render(
+      <Harness secret={`  ${VALID_WIF}\n`} onState={(s) => states.push(s)} />,
+    );
+    await flushDebounce();
+    expect(mockResolveIdentityFromWif).toHaveBeenCalledTimes(1);
+    // Resolver was called with the trimmed WIF, not the padded input.
+    expect(mockResolveIdentityFromWif).toHaveBeenCalledWith(sdk, VALID_WIF);
+    expect(states.at(-1)?.status).toBe("resolved");
+  });
+
+  it("survives DPNS lookup failure on resolved path (returns null name)", async () => {
+    mockResolveIdentityFromWif.mockResolvedValue({
+      identityId: "id-E",
+      identity: {},
+      matched: { id: 1, purpose: 0, securityLevel: 2 },
+      identityKey: {},
+    });
+    mockResolveDpnsName.mockRejectedValue(new Error("dpns broken"));
+
+    const states: WifPreviewState[] = [];
+    render(<Harness secret={VALID_WIF} onState={(s) => states.push(s)} />);
+    await flushDebounce();
+
+    expect(states.at(-1)).toEqual({
+      status: "resolved",
+      identityId: "id-E",
+      dpnsName: null,
+    });
+  });
+});